List Pages

Retrieve all pages for a project with powerful filtering, sorting, and pagination options. Perfect for building admin interfaces or content management workflows.

Endpoint

GET /pages

Headers

Name	Required	Description
`Authorization`	Yes	`Bearer $PAGEGUN_API_KEY`
`Content-Type`	No	`application/json`

Query Parameters

Name	Type	Required	Default	Description
`project_id`	string	Yes	-	Project ID to list pages for
`type`	string	No	`all`	Filter by page type: `page`, `article`, `docs`, `item`, or `all`
`subroute`	string	No	-	Filter by subroute (e.g., `pages`, `blog`, `docs`)
`status`	string	No	`all`	Filter by status: `draft`, `published`, `archived`, or `all`
`slug`	string	No	-	Filter by slug (exact match or partial with `*` wildcard)
`limit`	integer	No	`25`	Number of results per page (1-100)
`offset`	integer	No	`0`	Pagination offset
`sort`	string	No	`updated_at`	Sort field: `created_at`, `updated_at`, `page_name`, or `slug`
`order`	string	No	`desc`	Sort order: `asc` or `desc`
`created_after`	string	No	-	ISO 8601 timestamp to filter pages created after this date
`created_before`	string	No	-	ISO 8601 timestamp to filter pages created before this date
`updated_after`	string	No	-	ISO 8601 timestamp to filter pages updated after this date
`updated_before`	string	No	-	ISO 8601 timestamp to filter pages updated before this date
`include_content`	boolean	No	`false`	Include page content in response (increases response size)

Response

Returns a paginated list of page objects.

{
  "data": [
    {
      "id": "page_xyz789",
      "page_name": "Product Landing Page",
      "slug": "product-landing",
      "subroute": "pages",
      "type": "page",
      "status": "published",
      "url": "/product-landing",
      "meta": {
        "title": "Amazing Product - Get Started Today",
        "description": "Discover our amazing product features and benefits.",
        "image": "https://example.com/product-og.png"
      },
      "sections_count": 8,
      "word_count": 1250,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:00:00Z"
    },
    {
      "id": "page_abc456",
      "page_name": "Getting Started Guide",
      "slug": "getting-started",
      "subroute": "docs",
      "type": "docs",
      "status": "published",
      "url": "/docs/quick-start",
      "meta": {
        "title": "Getting Started - Documentation",
        "description": "Learn how to get started with our platform.",
        "image": null
      },
      "sections_count": 5,
      "word_count": 850,
      "created_at": "2024-01-12T08:00:00Z",
      "updated_at": "2024-01-18T16:30:00Z"
    }
  ],
  "meta": {
    "total": 47,
    "limit": 25,
    "offset": 0,
    "has_more": true,
    "filters": {
      "project_id": "proj_abc123",
      "type": "all",
      "status": "all"
    }
  }
}

Response Fields

Page Object

Field	Type	Description
`id`	string	Unique identifier for the page
`page_name`	string	Display name of the page
`slug`	string	URL slug for the page
`subroute`	string	Subroute/folder for the page
`type`	string	Page type: `page`, `article`, `docs`, or `item`
`status`	string	Publishing status: `draft`, `published`, or `archived`
`url`	string	Full URL path for the page
`meta`	object	SEO metadata for the page
`sections_count`	integer	Number of content sections in the page
`word_count`	integer	Approximate word count of page content
`created_at`	string	ISO 8601 timestamp when page was created
`updated_at`	string	ISO 8601 timestamp when page was last modified

Meta Object (SEO)

Field	Type	Description
`title`	string	Page title for SEO
`description`	string	Meta description for SEO
`image`	string	Social sharing image URL

Meta Object (Pagination)

Field	Type	Description
`total`	integer	Total number of pages matching the filter
`limit`	integer	Maximum number of items returned in this response
`offset`	integer	Number of items skipped for pagination
`has_more`	boolean	Whether there are more results available
`filters`	object	Applied filters for this request

Examples

Basic Request

curl -X GET "https://api.pagegun.com/pages?project_id=proj_abc123" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY"

Filter by Type and Status

curl -X GET "https://api.pagegun.com/pages?project_id=proj_abc123&type=article&status=published" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY"

Pagination and Sorting

curl -X GET "https://api.pagegun.com/pages?project_id=proj_abc123&limit=10&offset=20&sort=page_name&order=asc" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY"

Search by Slug Pattern

curl -X GET "https://api.pagegun.com/pages?project_id=proj_abc123&slug=blog-*" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY"

Filter by Date Range

curl -X GET "https://api.pagegun.com/pages?project_id=proj_abc123&created_after=2024-01-01T00:00:00Z&created_before=2024-02-01T00:00:00Z" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY"

Include Content in Response

curl -X GET "https://api.pagegun.com/pages?project_id=proj_abc123&include_content=true&limit=5" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY"

JavaScript Example

const listPages = async (projectId, filters = {}) => {
  const params = new URLSearchParams({
    project_id: projectId,
    ...filters
  });

  const response = await fetch(`https://api.pagegun.com/pages?${params}`, {
    headers: {
      'Authorization': `Bearer ${process.env.PAGEGUN_API_KEY}`
    }
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return response.json();
};

// Usage examples
const publishedArticles = await listPages('proj_abc123', {
  type: 'article',
  status: 'published',
  sort: 'created_at',
  order: 'desc'
});

const recentPages = await listPages('proj_abc123', {
  created_after: '2024-01-01T00:00:00Z',
  limit: 50
});

Error Responses

400 Bad Request

{
  "statusCode": 422,
  "name": "invalid_request",
  "message": "Invalid query parameter"
}

401 Unauthorized

{
  "statusCode": 401,
  "name": "unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden

{
  "statusCode": 403,
  "name": "forbidden",
  "message": "You don't have access to this project"
}

404 Not Found

{
  "statusCode": 404,
  "name": "not_found",
  "message": "Project not found"
}

429 Too Many Requests

{
  "statusCode": 429,
  "name": "rate_limit_exceeded",
  "message": "Too many requests. Please try again later."
}