GraphQL API: Queries and Mutations

While REST is excellent for standard integrations, modern Headless architectures (like Next.js, Nuxt.js, or Gatsby) often benefit from the precision of GraphQL.

PolyCMS provides a robust GraphQL endpoint, powered by Nuwave/Lighthouse, allowing your frontend to request exactly the data it needs—no more, no less.

The GraphQL endpoint is located at: http://localhost:8000/graphql

Authentication

Authentication for the GraphQL API works exactly the same as the REST API. You must pass a Laravel Sanctum Bearer token in the Authorization header.

Authorization: Bearer YOUR_TOKEN_HERE

GraphQL Playground

To explore the schema and test queries interactively, PolyCMS includes the GraphQL playground.

In your local development environment, navigate to http://localhost:8000/graphql to view the self-documenting schema and write test queries. (Note: This endpoint is disabled in production environments for security).

Writing Queries

Queries are used to read data from the system.

Example: Fetching a Paginated List of Posts

This query fetches the first 10 published posts, including their titles, slugs, and the names of the categories they belong to. Notice how we avoid over-fetching by specifically requesting only the fields we need.

query {
  posts(first: 10, status: "publish") {
    data {
      id
      title
      slug
      categories {
        name
      }
    }
    paginatorInfo {
      currentPage
      lastPage
      total
    }
  }
}

Example: Fetching a Single Product by Slug

query {
  product(slug: "iphone-15-pro") {
    id
    name
    price
    description_html
    stock_status
  }
}

Writing Mutations

Mutations are used to create, update, or delete data.

Example: Creating a Content Vote (Reaction)

PolyCMS features a generic content voting system. Here is how a frontend application might submit a "helpful" vote via GraphQL:

mutation {
  createContentVote(
    votable_type: "App\\Models\\Post",
    votable_id: 42,
    type: "helpful",
    ip_address: "192.168.1.1"
  ) {
    id
    type
    created_at
  }
}

Integrating with Frontends

If you are building a Headless SPA, we recommend using a GraphQL client like Apollo Client (for React/Vue) or URQL to handle caching, state management, and request batching when communicating with the PolyCMS GraphQL endpoint.