Your first API request

By the end of this walkthrough, you will have retrieved a story from your Prezly account. All three requests are reads: they do not create or change anything.

You need cURL, a personal API token or integration key, and access to a newsroom containing at least one story. A personal token needs sites:read and stories:read.

1. Load your tokenCopy Anchor Link

In Bash or Zsh, run the command below, paste your token, and press Enter. Input is hidden, so the token does not appear in the command you save in shell history.

read -r -s PREZLY_API_TOKEN
export PREZLY_API_TOKEN
printf '\n'

Keep that terminal open for the following requests. Do not enable shell tracing (set -x), which would print the expanded authorization header.

2. Find your newsroomCopy Anchor Link

Request the first five newsrooms your credential can access:

curl --fail-with-body --silent --show-error --get 'https://api.prezly.com/v2/newsrooms' \
  --header "Authorization: Bearer $PREZLY_API_TOKEN" \
  --header 'Accept: application/json' \
  --data-urlencode 'limit=5' \
  --data-urlencode 'offset=0'

A successful request returns 200 OK and a newsrooms array. The examples below show shortened, illustrative responses; your names and UUIDs will differ.

{
  "newsrooms": [
    {
      "uuid": "11111111-1111-4111-8111-111111111111",
      "name": "Acme newsroom"
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 5,
    "matched_records_number": 1,
    "total_records_number": 1
  }
}

Copy the uuid of the newsroom you want to read. The API uses the name newsroom for what Prezly calls a site.

If the array is empty, check that the credential has access to a newsroom. If the newsroom you need is on a later page, increase offset by limit and request that page. The response's pagination.matched_records_number tells you how many records match the request.

See all List Newsrooms parameters →

3. Find a story in that newsroomCopy Anchor Link

Replace YOUR_NEWSROOM_UUID below with the UUID you copied. Keep the query's single quotes: they preserve $in as part of the filter rather than treating it as a shell variable.

curl --fail-with-body --silent --show-error --get 'https://api.prezly.com/v2/stories' \
  --header "Authorization: Bearer $PREZLY_API_TOKEN" \
  --header 'Accept: application/json' \
  --data-urlencode 'query={"newsroom.uuid":{"$in":["YOUR_NEWSROOM_UUID"]}}' \
  --data-urlencode 'limit=5' \
  --data-urlencode 'offset=0'

query is a JSON filter. cURL's --data-urlencode encodes it for the URL, including the braces and quotation marks.

{
  "stories": [
    {
      "uuid": "22222222-2222-4222-8222-222222222222",
      "title": "Acme introduces its new collection"
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 5,
    "matched_records_number": 1,
    "total_records_number": 1
  }
}

Copy a story's uuid. An empty stories array is a successful response with no matching stories: check the newsroom UUID and whether that newsroom contains stories you can access. Use the same limit and offset approach if you want another page.

See all List Stories parameters →

4. Retrieve the storyCopy Anchor Link

Replace YOUR_STORY_UUID with the UUID from the stories response:

curl --fail-with-body --silent --show-error 'https://api.prezly.com/v2/stories/YOUR_STORY_UUID' \
  --header "Authorization: Bearer $PREZLY_API_TOKEN" \
  --header 'Accept: application/json; content-format=v6'

This request returns a single object under story, rather than a stories array:

{
  "story": {
    "uuid": "22222222-2222-4222-8222-222222222222",
    "title": "Acme introduces its new collection",
    "format_version": 6
  }
}

The response also includes the story's content and related fields. The Accept header asks Prezly to return content in format v6 so your integration can work with one format. It does not change the stored story.

Explore the full Get Story response →

Read the same story with JavaScriptCopy Anchor Link

This example uses Node.js 22 or later and its built-in fetch. Save it as read-story.mjs, replace YOUR_STORY_UUID, and run node read-story.mjs in the terminal where you exported PREZLY_API_TOKEN.

const token = process.env.PREZLY_API_TOKEN;
if (!token) throw new Error('Set PREZLY_API_TOKEN before running this script.');

const storyUuid = 'YOUR_STORY_UUID';
const response = await fetch(`https://api.prezly.com/v2/stories/${storyUuid}`, {
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: 'application/json; content-format=v6',
  },
});

if (!response.ok) {
  throw new Error(`Prezly returned HTTP ${response.status}. Check the response and your access.`);
}

const { story } = await response.json();
console.log(story.uuid, story.title);

If a request failsCopy Anchor Link

cURL's --fail-with-body keeps the error response visible and returns a nonzero exit code for HTTP errors. Check the status and any error code; a failed request is different from an empty results array.

• 401: check or replace the bearer token.
• 403: check the required scopes and permissions.
• 404 for a story: copy its UUID again and check access to its newsroom.

When you are finished, remove the token from this shell with unset PREZLY_API_TOKEN.

You have now followed the complete read path from newsroom to story. Next, learn how to paginate and sort lists, filter results, and handle errors. Use the API reference for complete parameters and response models.

To display the story in a custom newsroom, continue with Story rendering.