# Quickstart

**Goal:** list the published entries of one [content type](https://dev.acquia.com/start-here/glossary/#content-type-bundle) on your [site](https://dev.acquia.com/start-here/glossary/#site) from your terminal.

## What you'll have when you're done

- The [machine name](https://dev.acquia.com/start-here/glossary/#machine-name) of a content type, read from your site's [JSON:API Query Builder](https://dev.acquia.com/start-here/glossary/#jsonapi-query-builder).
- One successful `GET /api/node/{type}` request and a map of where entries, IDs, and fields live in the response.
- Proof that query parameters work, by limiting the result with `page[limit]`.

## Prerequisites

- The [API client](https://dev.acquia.com/start-here/glossary/#api-client) from the [auth quickstart](https://dev.acquia.com/source-cms/authenticate/quickstart/): you'll reuse its `.env` file.
- [Node.js](https://nodejs.org/) 20.6 or later for the JSON:API Client and JavaScript paths, or [`curl`](https://curl.se/) (preinstalled on macOS and Linux).

## Steps

1. ### Find your content type's machine name

   In your site's left sidebar, go to `API > JSON:API Query Builder`. In the `Entity Type` dropdown select the content [entity type](https://dev.acquia.com/start-here/glossary/#entity-type) (`node`), then pick your content type in the `Bundle` dropdown.

   The `Request URL` section now shows the exact URL for that type. The last path segment is the machine name:

   ```
   https://your-site.example.com/api/node/article
   ```

   The machine name (`article` here) is what the API uses. It is lowercase with underscores, and often differs from the label editors see: a type labeled "News post" might be `news_post`. The steps below use `article`; substitute yours.

   No browser handy? The API root you called at the end of the [auth quickstart](https://dev.acquia.com/source-cms/authenticate/quickstart/) already lists every type: look for the `links` entries starting `node--`: the part after the double dash is the machine name.

2. ### List the entries

   Call the collection endpoint with the credentials from the auth quickstart's `.env`:

   **JSON:API Client**

   The [Drupal API Client](https://dev.acquia.com/start-here/glossary/#drupal-api-client) addresses the type by its resource type string: entity type and machine name joined with a double dash, `node--article` (the same format the response's `type` member uses). In a directory with the `.env` file:

   ```bash
   npm install @drupal-api-client/json-api-client
   ```

   ```js
   // list-articles.mjs
   import {
     JsonApiClient,
   } from "@drupal-api-client/json-api-client";

   const client = new JsonApiClient(
     process.env.DRUPAL_SITE_URL,
     {
       // Source CMS serves JSON:API at /api
       apiPrefix: "api",
       authentication: {
         type: "OAuth",
         credentials: {
           grantType: "client_credentials",
           clientId: process.env.DRUPAL_CLIENT_ID,
           clientSecret: process.env.DRUPAL_CLIENT_SECRET,
         },
       },
     },
   );

   const articles = await client.getCollection(
     "node--article",
   );
   console.log(JSON.stringify(articles, null, 2));
   ```

   ```bash
   node --env-file=.env list-articles.mjs
   ```

   No token handling: the client exchanges the credentials for a token itself and refreshes it when it expires.

   **JavaScript**

   Get a token, then `fetch` the collection URL with it. In a directory with the `.env` file:

   ```js
   // list-articles.mjs
   const {
     DRUPAL_SITE_URL,
     DRUPAL_CLIENT_ID,
     DRUPAL_CLIENT_SECRET,
   } = process.env;

   const tokenHeaders = {
     "Content-Type": "application/x-www-form-urlencoded",
   };

   const tokenResponse = await fetch(
     `${DRUPAL_SITE_URL}/oauth/token`,
     {
       method: "POST",
       headers: tokenHeaders,
       body: new URLSearchParams({
         grant_type: "client_credentials",
         client_id: DRUPAL_CLIENT_ID,
         client_secret: DRUPAL_CLIENT_SECRET,
       }),
     }
   );
   const { access_token } = await tokenResponse.json();

   const response = await fetch(
     `${DRUPAL_SITE_URL}/api/node/article`,
     {
       headers: {
         Accept: "application/vnd.api+json",
         Authorization: `Bearer ${access_token}`,
       },
     }
   );
   console.log(
     JSON.stringify(await response.json(), null, 2),
   );
   ```

   ```bash
   node --env-file=.env list-articles.mjs
   ```

   **curl**

   Load your `.env` into the shell, get a token, and call the collection endpoint:

   ```bash
   set -a; source .env; set +a  # export every variable in .env into this shell

   TOKEN=$(curl -s -X POST \
     "$DRUPAL_SITE_URL/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "client_id=$DRUPAL_CLIENT_ID" \
     -d "client_secret=$DRUPAL_CLIENT_SECRET" \
     | sed -n 's/.*"access_token": *"\([^"]*\)".*/\1/p')

   echo $TOKEN  # a long string; empty means the token request failed

   curl -s "$DRUPAL_SITE_URL/api/node/article" \
     -H "Accept: application/vnd.api+json" \
     -H "Authorization: Bearer $TOKEN"
   ```

   If `echo $TOKEN` prints nothing, the token request failed and the next call would 401 two steps from the real error: re-run the token `curl` without the trailing `| sed …` to see the error response itself.

   A `200` response returns the first page of published entries of that type, up to the [`page[limit]` default of 50](https://dev.acquia.com/source-cms/reference/query-parameters/#pagelimit-and-pageoffset-pagination). Beyond that, follow `links.next`. (The API sends one compact line; shown formatted and trimmed here.)

   ```json
   {
     "jsonapi": {
       "version": "1.1",
       "meta": {
         "links": {
           "self": {
             "href": "http://jsonapi.org/format/1.1/"
           }
         }
       }
     },
     "data": [
       {
         "type": "node--article",
         "id": "3f9a2b1e-6c4d-4a8e-9b7f-1d2e3c4b5a69",
         "links": {
           "self": {
             "href": "https://your-site.example.com/api/node/article/3f9a2b1e-6c4d-4a8e-9b7f-1d2e3c4b5a69?resourceVersion=id%3A1"
           }
         },
         "attributes": {
           "langcode": "en",
           "status": true,
           "title": "Spring launch recap",
           "created": "2026-05-11T09:30:52+00:00",
           "changed": "2026-05-12T14:02:10+00:00",
           "path": {
             "alias": null,
             "pid": null,
             "langcode": "en"
           }
         },
         "relationships": {
           "node_type": { "…": "…" },
           "uid": { "…": "…" }
         }
       },
       {
         "type": "node--article",
         "id": "…more entries…",
         "attributes": { "…": "…" }
       }
     ],
     "meta": { "count": 5 },
     "links": { "self": {
      "href": "https://your-site.example.com/api/node/article"
     } }
   }
   ```

   Where to look:

   - **`data`**: the entries. One object per entry.
   - **`type`**: entity type plus bundle machine name, joined with a double dash: `node--article`.
   - **`id`**: the entry's UUID, its stable identifier. One entry lives at `/api/node/article/{id}`.
   - **`attributes`**: the entry's [field](https://dev.acquia.com/start-here/glossary/#field) values, keyed by field machine name. `title`, `created`, `changed`, `status`, `langcode`, and `path` appear on every content type; your type's own fields appear alongside them, so your list will be longer and different.
   - **`relationships`**: pointers to related entries and metadata. Every type has `node_type` and `uid`; reference fields your type defines (media, taxonomy terms) appear here too. The [querying guide](https://dev.acquia.com/source-cms/content-api/guide/) shows how to pull them into the same response.

3. ### Limit the result with `page[limit]`

   Add one query parameter:

   **JSON:API Client**

   Query parameters are built with the `drupal-jsonapi-params` package, the client's companion for everything you'd otherwise hand-write into the URL:

   ```bash
   npm install drupal-jsonapi-params
   ```

   ```js
   // add to list-articles.mjs
   import {
     DrupalJsonApiParams,
   } from "drupal-jsonapi-params";

   const queryString = new DrupalJsonApiParams()
     .addPageLimit(2)
     .getQueryString();
   const limited = await client.getCollection(
     "node--article",
     { queryString },
   );
   console.log(JSON.stringify(limited, null, 2));
   ```

   `getQueryString()` produces `page[limit]=2` (URL-encoded), so you never escape brackets yourself.

   **JavaScript**

   Append the parameter to the URL; `fetch` encodes the square brackets for you:

   ```js
   const limited = await fetch(
     `${DRUPAL_SITE_URL}/api/node/article?page[limit]=2`,
     {
       headers: {
         Accept: "application/vnd.api+json",
         Authorization: `Bearer ${access_token}`,
       },
     }
   );
   console.log(
     JSON.stringify(await limited.json(), null, 2),
   );
   ```

   **curl**

   Add the parameter, and add `-g` to curl, which stops it treating the square brackets as glob characters:

   ```bash
   curl -g -s "$DRUPAL_SITE_URL/api/node/article\
   ?page[limit]=2" \
     -H "Accept: application/vnd.api+json" \
     -H "Authorization: Bearer $TOKEN"
   ```

   `data` now holds at most 2 entries, and when more exist, `links` gains ready-made `next` and `last` URLs:

   ```json
   {
     "data": [
       { "type": "node--article", "…": "…" },
       { "type": "node--article", "…": "…" }
     ],
     "links": {
       "last": {
         "href": "https://your-site.example.com/api/node/article?page%5Boffset%5D=4&page%5Blimit%5D=2"
       },
       "next": {
         "href": "https://your-site.example.com/api/node/article?page%5Boffset%5D=2&page%5Blimit%5D=2"
       },
       "self": {
         "href": "https://your-site.example.com/api/node/article?page%5Blimit%5D=2"
       }
     }
   }
   ```

   That's the whole mechanism: everything you will ever ask the Content API for (filters, fields, related entries, sorting) is a query parameter on a `GET`, shaping the same response you just read.

## What just happened

`GET /api/node/{type}` is the collection endpoint for one content type, and query parameters shape what it returns. Your site ships two companion tools for going further. The `JSON:API Query Builder` (`API > JSON:API Query Builder`) builds these queries visually (fields, filters, includes, sort), previews live responses, and generates code samples. The per-site `OpenAPI documentation` (`API > OpenAPI documentation`) lists every endpoint your site exposes, with interactive try-it-out calls.

## When something goes wrong

**`"data": []` with `200 OK`**: the request worked but returned nothing. Three distinct causes:

- *You queried the wrong type.* The URL names a real type, but not the one your entries belong to (for example `node/page` while your content is `node/article`). Check: re-select the entity type and bundle in the Query Builder and compare its `Request URL` with yours; remember it's the machine name, not the label, and it's case-sensitive lowercase.
- *The type has no published content.* The name is right but nothing is published. Check: open your site's content list, filter to that type, and confirm at least one entry is published.
- *The entries exist but you're not allowed to see them.* When `data` is empty (or shorter than the response's `meta.count`) and the response carries a `meta.omitted` block (`"detail": "Some resources have been omitted because of insufficient authorization."`), the entries are unpublished or access-restricted, not missing. Check `meta.omitted` before concluding there's no content. Entries created via the API are unpublished by default. See the [writing content guide](https://dev.acquia.com/source-cms/content-api/writing-content/).

**`404 Not Found`**: the type in the URL doesn't exist at all: a label used in place of the machine name (`node/Article`, `node/news post`), wrong case, or a typo. Copy the URL from the Query Builder's `Request URL` section instead of typing it.

**`401 Unauthorized`**: the token is missing or expired (tokens expire after `expires_in` seconds: 300, so 5 minutes). In the JavaScript path, rerun the script for a fresh token; in the curl path, re-run the `TOKEN=` command from step 2 in the same shell. The JSON:API Client refreshes tokens itself, so a 401 there points at the credentials. More cases in the [auth guide's troubleshooting](https://dev.acquia.com/source-cms/authenticate/guide/#when-something-goes-wrong).

**`SyntaxError: Unexpected token '<', "<!DOCTYPE "... is not valid JSON`** from the JSON:API Client: the client called its default base path `/jsonapi` and got an HTML page back. Source CMS serves the API at `/api`; construct the client with `apiPrefix: "api"`, as in step 2.

**`curl: (3) bad range in URL position …`**: curl interpreted the `[` `]` in `page[limit]` as glob syntax. Add `-g` (globoff), as in step 3. Note that `-s` silences this error entirely: if a bracketed request prints nothing at all, rerun it without `-s` to see what curl is complaining about.

## Next steps

- [First fetch](https://dev.acquia.com/source-cms/content-api/first-fetch/): turn this call into your first rendered page.
- [Querying guide](https://dev.acquia.com/source-cms/content-api/guide/): filters, sparse fieldsets, related entries, pagination, and sorting, composed into real queries.
- `API > JSON:API Query Builder` on your site: build and preview any query visually, then copy the URL or generated code.
- `API > OpenAPI documentation` on your site: the interactive list of every endpoint your site exposes.
