GuidesAPI Reference
Guides
Start typing to search…

Updates FAQ

Content API: How Stories Update

This guide explains how stories update in the Content API, covering both individual content items and stories that span multiple items.

Content Items

A content item is a discrete piece of content within the API. Items can take many forms — stories, text assets, images, graphics, and more.

For the purposes of this documentation, we focus on text-based output - which usually consists of stories or smaller text assets which we call latest posts.

How Items Are Updated

Text items can be updated in three ways.

Important Corrections

Corrections do alter the editorial substance of the item.

These occur when:

  • Additional content is added to the item.
  • Important factual details are changed or clarified.

Corrections will include an editorial note explaining what has changed.

Non-Meaningful Updates

Non-meaningful updates do not alter the editorial substance of the item.

These occur when:

  • Metadata is modified, such as adding or changing tags.
  • Media is added for a product like PA Ready. These changes are not visible in Create or the Newswire.
  • Minor spelling mistakes are corrected.

Embargo Lifts

  • Unembargoed customers: The item will appear in your feed for the first time. However it will contain metadata which shows it as being a later version and will contain correction metadata.
  • Embargoed customers: The item will appear the same as any other correction, accompanied by a description note confirming the embargo has lifted and the content may now be reported on.

Identifying the Update Type

Each updated item includes a signal entry in the subject array that indicates whether the update is a correction or a non-meaningful update.

Corrections

A correction is indicated by the sig:correction signal code.

JSON (NinJS):

"subject": [
  {
    "code": "sig:correction",
    "name": "Correction",
    "profile": "sig",
    "scheme": "http://cv.iptc.org/newscodes/signal/",
    "rel": "signal"
  }
]

RSS:

<category domain="urn:pa:subject:sig">Correction</category>

ATOM:

<category term="sig:correction" scheme="urn:pa:subject:sig" label="Correction" />

Note: If a story was originally published under embargo, customers who do not receive embargoed content will see a sig:correction signal on the first version they receive — even though it is their initial delivery of the item. This is because the embargo lift is treated as a correction in the publishing workflow.

Non-Meaningful Updates

A non-meaningful update is indicated by the sig:update signal code.

JSON (NinJS):

"subject": [
  {
    "code": "sig:update",
    "name": "Update",
    "profile": "sig",
    "scheme": "http://cv.iptc.org/newscodes/signal/",
    "rel": "signal"
  }
]

RSS:

<category domain="urn:pa:subject:sig">Update</category>

ATOM:

<category term="sig:update" scheme="urn:pa:subject:sig" label="Update"/>

Tip: If the signal entry is absent from the subject array, the item is the original version and has not been updated.

Ordering Your Feed

There are three timestamps available for ordering results. Each behaves differently, so choosing the right one is important.

firstcreated

Set the first time an item is published. This value never changes.

Note on embargoed content: For stories originally published under embargo, firstcreated retains the original publication time — it does not update when the embargo lifts. If you are an unembargoed customer ordering by firstcreated, these stories will appear inline at their original position in the feed and may be buried among older content.

If this behaviour is causing issues for your integration look at using the issued time or please contact us with feedback.

Parameter

Descending - &sort=firstcreated:desc

Ascending - &sort=firstcreated:asc

Important: If you are sorting by firstcreated and need to perform a time-based search using start/end parameters, you must also include rangeField=firstcreated in your query.

versioncreated

Updated every time the item is modified, regardless of the nature of the change.

Ordering by versioncreated means every update — including non-meaningful ones — will push the item back to the top of the feed. This is useful if you need to ingest every change published to your service.

Parameter

Descending - &sort=versioncreated:desc

Ascending - &sort=versioncreated:asc

issued

A curated timestamp reflecting the most recent editorially significant moment. It is set based on whichever of the following occurred most recently:

  • The item was first published (mirrors the firstcreated value).
  • The item received a correction.
  • The item's embargo expired.

Recommended for most use cases. If you want important updates to resurface a story without every minor modification doing the same, use issued as your sort parameter.

Parameter

Descending - &sort=issued:desc

Ascending - &sort=issued:asc

Important: If you are sorting by issued and need to perform a time-based search using start/end parameters, you must also include rangeField=issued in your query.

Tiebreaker sort parameter

Because it is feasible to have multiple items with the same timestamp it is recommended to add a second sort parameter of uri

&sort=issued:desc&sort=uri

This way when you're paging through API results you won't get different ordering for the same items.

Events

What Is an Event?

In PA terminology, an event represents all content sharing the same Topic and Keyword pairing on a given date.

Identifying an Item's Event

Each item contains an event array that indicates which event(s) it belongs to.

There will always be an entry with a profile value of partOf which is the item's event.

Please see below for an exmaple.

Multiple Events (Sidebars)

An item may be associated with two events when it is a sidebar. In this case, inspect the rel field to determine:

  • Which event is the item's own event — identified by "rel": "partOf":
{
  "code": "paevent:41604f933badd1976da66363bbade134c8649746c5cb7c4c2a511bf63cc24e84",
  "name": "Prisons Huntley Case 26/02/2026",
  "profile": "paevent",
  "scheme": "https://content.api.pressassociation.io/v1/event",
  "rel": "partOf"
}
  • Which event is the parent event that this item is a sidebar of — identified by "rel": "relatedTo":
{
  "code": "paevent:1d36d19a56a59330eb707f1a6cffde1d26f56c0377d6bc174086e2bf89929f0c",
  "name": "Prisons Huntley 26/02/2026",
  "profile": "paevent",
  "scheme": "https://content.api.pressassociation.io/v1/event",
  "rel": "relatedTo"
}

Finding Other Stories in an Event

Use the event query parameter on the /item endpoints to retrieve all content associated with a given event:

GET /item?event=paevent:{eventId}.partOf

This can be combined with the type and profile parameters to filter for specific content types — for example, returning only related images, video, or text stories.

Retrieving the Main Story for a Sidebar

If you have a sidebar item and need to find its parent story, filter the /item endpoint using the relatedTo relationship:

GET /item?event=paevent:{eventId}.relatedTo

This returns items belonging to the parent event that the sidebar is associated with.

Updated 17 days ago