{
  "posts": [
    {
      "id": "post_abc123def456",
      "slug": "getting-started-with-cms-integration",
      "title": "Getting Started with CMS Integration",
      "content": "<p>Learn how to integrate your content management system...</p>",
      "coverImage": "https://images.example.com/media/cms-integration-guide.webp",
      "description": "A comprehensive guide to integrating your CMS with modern web frameworks...",
      "publishedAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-20T14:22:33.456Z",
      "attribution": null,
      "authors": [
        {
          "id": "author_xyz789",
          "name": "John Smith",
          "image": "https://images.example.com/avatars/john-smith.jpg"
        }
      ],
      "category": {
        "id": "cat_tutorials123",
        "name": "Tutorials",
        "slug": "tutorials"
      },
      "tags": [
        {
          "id": "tag_integration456",
          "name": "Integration",
          "slug": "integration"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 5,
    "currentPage": 1,
    "nextPage": null,
    "previousPage": null,
    "totalPages": 1,
    "totalItems": 2
  }
}
MarbleCMS API uses offset-based pagination for endpoints that return multiple items. Pagination metadata is included in every response to help you navigate through large datasets efficiently.

How Pagination Works

When you request a list of resources (like posts), the API automatically includes pagination information in the response. This allows you to:
  • Control how many items are returned per request
  • Navigate to specific pages
  • Understand the total size of the dataset
  • Build pagination UI components

Query Parameters

limit
integer
default:"10"
The maximum number of items to return per page.Range: 1-200 items per page
page
integer
default:"1"
The page number to retrieve. Pages start at 1.Minimum: 1

Pagination Response

Every paginated response includes a pagination object with the following fields:
pagination
object
Metadata about the current page and navigation options.

Request Examples

Get the first page with default limit (10 items):
cURL
curl -X GET 'https://api.marblecms.com/v1/YOUR_WORKSPACE_ID/posts'
{
  "posts": [
    {
      "id": "post_abc123def456",
      "slug": "getting-started-with-cms-integration",
      "title": "Getting Started with CMS Integration",
      "content": "<p>Learn how to integrate your content management system...</p>",
      "coverImage": "https://images.example.com/media/cms-integration-guide.webp",
      "description": "A comprehensive guide to integrating your CMS with modern web frameworks...",
      "publishedAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-20T14:22:33.456Z",
      "attribution": null,
      "authors": [
        {
          "id": "author_xyz789",
          "name": "John Smith",
          "image": "https://images.example.com/avatars/john-smith.jpg"
        }
      ],
      "category": {
        "id": "cat_tutorials123",
        "name": "Tutorials",
        "slug": "tutorials"
      },
      "tags": [
        {
          "id": "tag_integration456",
          "name": "Integration",
          "slug": "integration"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 5,
    "currentPage": 1,
    "nextPage": null,
    "previousPage": null,
    "totalPages": 1,
    "totalItems": 2
  }
}
{
  "posts": [],
  "pagination": {
    "limit": 10,
    "currentPage": 1,
    "nextPage": null,
    "previousPage": null,
    "totalPages": 0,
    "totalItems": 0
  }
}
{
  "error": "Invalid page number",
  "details": {
    "message": "Page 2 does not exist.",
    "totalPages": 1,
    "requestedPage": 2
  }
}

Paginated Endpoints

The following endpoints support pagination:

Best Practices

Optimize Performance: Use smaller page sizes (5-20 items) for better performance, especially on mobile devices.
Handle Empty Results: Always check if the posts array is empty and handle the empty state in your UI.
Navigation Logic: Use nextPage and previousPage values to build navigation controls. These fields will be null when navigation in that direction isn’t possible.

Error Handling