Resources and identifiers

A Prezly integration works with resources: newsrooms, stories, contacts, and the other records in your account. Start with the relationship you need, then use the endpoint for that resource. The JSON field names and endpoint paths do not always match the labels you see in the Prezly interface.

Sites are newsrooms in the APICopy Anchor Link

Prezly calls your websites sites. The API uses the older name newsroom, including the /newsrooms endpoint and a story's newsroom field. Both names refer to the same resource.

The simplest content relationship is:

Prezly account
└── Newsroom (site)
    ├── Story in one language
    └── Another story or translation

A story belongs to a newsroom. A translation is another story record with its own UUID, linked to the other language versions. Do not use the original story's UUID as the identifier for every translation.

Start with List Newsrooms, filter List Stories to the newsroom you need, then retrieve one with Get Story. The first request walkthrough follows this path end to end.

Use UUIDs for newsrooms and storiesCopy Anchor Link

Copy the resource's uuid from an API response and keep it as a string. For example, this shortened story response contains both the story's identifier and a reference to its newsroom:

{
  "story": {
    "uuid": "22222222-2222-4222-8222-222222222222",
    "title": "Acme introduces its new collection",
    "newsroom": {
      "uuid": "11111111-1111-4111-8111-111111111111",
      "name": "Acme newsroom"
    }
  }
}

Use the story UUID in /v2/stories/YOUR_STORY_UUID. Use the newsroom UUID when filtering stories by newsroom.uuid. These examples use illustrative identifiers; replace them with values returned for your account.

Some responses also contain a numeric id. Older integrations and some endpoints still accept numeric IDs, but new newsroom and story integrations should use UUIDs. Check the reference for other resource types: not every identifier is a UUID. Language codes, country codes, slugs, and IDs have different purposes; a title or public URL is not a substitute for a resource UUID.

Lists and individual resources have different shapesCopy Anchor Link

A list returns an array named for the resource, such as newsrooms or stories, plus pagination information. An individual story response wraps the object in story.

A list item or nested reference can contain fewer fields than the full resource. For example, a story's newsroom reference identifies its site without embedding every site setting. Use the response schema for the endpoint you call; do not assume a nested object contains the entire resource or that a list item contains full story content.

Choose the resource for your taskCopy Anchor Link

Other resources support these workflows: categories organize stories, contact tags organize contacts, and media resources hold images and files. Their endpoints and permissions are specific to the task; they are not interchangeable with the parent resource.

Access is part of every requestCopy Anchor Link

The API only returns records available to the credential you send. A token scope such as stories:read allows a type of operation; it does not grant access to every newsroom or account. An empty list can mean no records match within your access, and knowing a UUID does not grant permission to read that resource.

For a public website, separately choose which stories are suitable for visitors. An authenticated response can contain content that is not public. Successful authentication is not a publication or visibility check.

See Authentication for credential types and permissions. Once the relationships are clear, use the API reference to check the exact request and response shape.