Content APIs

Pulling Content

GraphQL

Every content type automatically gets a graphql Collection that can be queried. In our case, since we created an article content type, the content will be available in a collection called ArticleCollection . dotCMS makes it easy to query the collection of Articles - it uses a search engine/lucene query syntax to allow for complex content queries. Every dotCMS instance ships with a GraphQL playground which you can use to explore the dotCMS Graph schema. In our simple example case, we can select the last 10 articles published by running the following query:

query graphQuery {
  ArticleCollection(query: "+title:*", limit: 10, offset: 0, sortBy: "article.publishDate desc") {
    title
    tags
    publishDate
    image{
      size
      width
      height
      idPath
      sha256
    }
  }
}

This will return a result like:

{
  "data": {
    "ArticleCollection": [
      {
        "title": "This Northern California city is the top U.S. destination among homebuyers looking to relocate",
        "tags": [
          "california",
          "sacramento",
          "conde nast",
          "travel",
          "city"
        ],
        "publishDate": "2025-05-21 10:00:00.0",
        "image": {
          "size": 51867,
          "width": 612,
          "height": 459,
          "idPath": "/dA/b939426dab/image/sacramento-from-above.jpg?language_id=1",
          "sha256": "17f33fe5348f6f696c1c04369a8ddfcd93e835a8cb1065df9e1901098bdde02f"
        }
      },
      ........
    ]
  }
}

The graphql API also has access to the PageAPI and the NavAPI which are especially helpful when you want to enable headless page building to render pages and navigation menu items.

Finally, if you content has relationships to other content objects, GraphQL allows you to recurse down the content graph to pull the related content as well. For example, if our Article type had a relationship to an Author type, we could grab all the data in one shot, without having to re-hydrate the author content by id:

query graphQuery {
  ArticleCollection(query: "+title:*", limit: 10, offset: 0, sortBy: "article.publishDate desc") {
    title
    teaser
    tags
    publishDate
    author{
      firstName
      lastName
      title
      biography
      headshot{
         width
         height
         idPath
         fileName
      }
    }
  }
}

One interesting capability of dotCMS's graphql endpoint is that it can be queried using a HTTP POST or a HTTP GET. The benefits of using a GET to query GraphQL is that it allows the query results to be cached by upstream systems like a CDN for maximum API performance. When querying the graphql using a GET, we recommend passing a query parameter as an id (which can be the hash of the query) so that a caching CDN can distinguish between GraphQL queries.

REST Content Queries

Like the Graphql APIs, content can be queried using plain REST API calls. dotCMS has endpoints to allow you to query and retrieve content.

GET /api/v1/content/{contentId}

This endpoint will return a single content object by identifier (unchanging id for all versions and languages of content) or by inode, which is the specific version id of the content.

POST /api/content/_search

curl -XPOST 'https://local.dotcms.site:8443/api/content/_search' \
-H 'Content-Type: application/json' \
-d '{
"query": "+contentType:Article tags:'pulling content'  +languageId:1 +live:true",
"sort": "Article.publishDate desc",
"limit": 20,
"offset": 0
}'