> ## Documentation Index > Fetch the complete documentation index at: https://docs.marblecms.com/llms.txt > Use this file to discover all available pages before exploring further. # List posts > Get a paginated list of published posts with optional filtering ## OpenAPI ````yaml https://api.marblecms.com/openapi.json get /v1/posts openapi: 3.1.0 info: title: Marble API version: 1.0.0 description: A headless CMS API for managing and delivering content programmatically. servers: - url: https://api.marblecms.com description: Production security: - apiKey: [] paths: /v1/posts: get: tags: - Posts summary: List posts description: Get a paginated list of published posts with optional filtering parameters: - schema: type: integer example: 10 description: Number of posts per page (1-100) required: false description: Number of posts per page (1-100) name: limit in: query - schema: type: integer example: 1 description: Page number required: false description: Page number name: page in: query - schema: type: string enum: - asc - desc default: desc example: desc description: Sort order by publishedAt required: false description: Sort order by publishedAt name: order in: query - schema: type: array items: type: string example: - tech - news description: Category slugs to include required: false description: Category slugs to include name: categories in: query style: form explode: false - schema: type: array items: type: string example: - changelog description: Category slugs to exclude required: false description: Category slugs to exclude name: excludeCategories in: query style: form explode: false - schema: type: array items: type: string example: - javascript - react description: Tag slugs to include required: false description: Tag slugs to include name: tags in: query style: form explode: false - schema: type: array items: type: string example: - outdated description: Tag slugs to exclude required: false description: Tag slugs to exclude name: excludeTags in: query style: form explode: false - schema: type: string example: nextjs description: Search query for title and content required: false description: Search query for title and content name: query in: query - schema: $ref: '#/components/schemas/ContentFormat' required: false description: Content format (html or markdown) name: format in: query - schema: type: string enum: - 'true' - 'false' example: 'true' description: Filter by featured status required: false description: Filter by featured status name: featured in: query - schema: type: string enum: - published - draft - all default: published example: published description: >- Filter by post status. Use 'published' for live posts, 'draft' for unpublished posts, or 'all' for both. required: false description: >- Filter by post status. Use 'published' for live posts, 'draft' for unpublished posts, or 'all' for both. name: status in: query responses: '200': description: Paginated list of posts content: application/json: schema: $ref: '#/components/schemas/PostsListResponse' '400': description: Invalid query parameters or page number content: application/json: schema: anyOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/PageNotFound' '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/ServerError' components: schemas: ContentFormat: type: string enum: - html - markdown example: html description: Content format (html or markdown) PostsListResponse: type: object properties: posts: type: array items: $ref: '#/components/schemas/Post' pagination: $ref: '#/components/schemas/Pagination' required: - posts - pagination Error: type: object properties: error: type: string example: Invalid query parameters details: type: array items: type: object properties: field: type: string example: limit message: type: string example: Expected number, received string required: - field - message message: type: string example: Validation failed required: - error PageNotFound: type: object properties: error: type: string enum: - Invalid page number details: type: object properties: message: type: string example: Page 10 does not exist. totalPages: type: integer example: 5 requestedPage: type: integer example: 10 required: - message - totalPages - requestedPage required: - error - details ServerError: type: object properties: error: type: string example: Internal server error message: type: string example: Failed to fetch resource required: - error Post: type: object properties: id: type: string example: cryitfjp5678mn09qrstuvwx slug: type: string example: getting-started-with-nextjs title: type: string example: Getting Started with Next.js status: type: string enum: - published - draft example: published featured: type: boolean example: false coverImage: type: string nullable: true example: https://media.marblecms.com/cover.jpg description: type: string example: A beginner's guide to Next.js publishedAt: type: string format: date-time example: '2024-01-15T10:00:00Z' updatedAt: type: string format: date-time example: '2024-01-16T12:00:00Z' authors: type: array items: $ref: '#/components/schemas/AuthorRef' category: $ref: '#/components/schemas/CategoryRef' tags: type: array items: $ref: '#/components/schemas/TagRef' fields: type: object additionalProperties: anyOf: - type: string - type: number - type: boolean - type: array items: type: string - nullable: true description: Custom field values keyed by field key example: release_date: '2024-01-15' priority_score: 5 hashtags: - '#javascript' - '#nextjs' content: type: string example:

Hello world

required: - id - slug - title - status - featured - coverImage - description - publishedAt - updatedAt - authors - category - tags - fields - content Pagination: type: object properties: limit: type: integer minimum: 0 exclusiveMinimum: true example: 10 currentPage: type: integer minimum: 0 exclusiveMinimum: true example: 1 nextPage: type: integer nullable: true example: 2 previousPage: type: integer nullable: true example: null totalPages: type: integer example: 5 totalItems: type: integer example: 42 required: - limit - currentPage - nextPage - previousPage - totalPages - totalItems AuthorRef: type: object properties: id: type: string example: cryitfjp1234jl04vdnycek8 name: type: string example: John Doe image: type: string nullable: true example: https://media.marblecms.com/avatar.jpg bio: type: string nullable: true example: Technical writer and developer role: type: string nullable: true example: Editor slug: type: string example: john-doe socials: type: array items: $ref: '#/components/schemas/SocialRef' required: - id - name - image - bio - role - slug - socials CategoryRef: type: object properties: id: type: string example: cryitfjp1234jl04vdnycek8 name: type: string example: Technology slug: type: string example: technology description: type: string nullable: true example: Tech news and tutorials required: - id - name - slug - description TagRef: type: object properties: id: type: string example: cryitfjp1234jl04vdnycek8 name: type: string example: JavaScript slug: type: string example: javascript description: type: string nullable: true example: JavaScript tutorials required: - id - name - slug - description SocialRef: type: object properties: url: type: string format: uri example: https://twitter.com/johndoe platform: type: string example: twitter required: - url - platform securitySchemes: apiKey: type: apiKey in: header name: Authorization description: Your Marble API key ````