Skip to contentDevelopersPrezly website
Stories

Search Stories

Search story summaries with a JSON request body and inspect the returned pagination.

Personal token scopes: stories:read. Your account must also have access to the requested data. Authentication

Read the guide

POST
/stories/search

This endpoint works very similar to Stories List API, except it accepts all params within the request body.

You can build a complex filtering criteria by using Prezly Query Language expressions in the query property.

Supported filters

FilterComparisonsTypeDescription
uuid$eq, $ne, $in, $ninstring, string[]Filter by uuid
id$in, $ninintegerFilter by id (deprecated)
format_version$eq, $neintegerFilter for legacy HTML stories (1) or structured content stories (3, 4, 5, 6)
slug$eq, $ne, $in, $ninstring, string[]Filter by slug
status$in, $ninstring[]Filter by lifecycle status (uninitialized, draft, scheduled, embargo, published)
visibility$in, $ninstring[]Filter by visibility (public, embargo, private, confidential)
language$in, $ninstring[]Filter by language code
locale$in, $ninstring[]Filter by a specific locale code, such as en_BE.
newsroom.uuid$in, $ninstring[]Filter by Newsroom uuid
newsroom.id$in, $nininteger[]Filter by Newsroom id
author.id$in, $nininteger[]Filter by Author id
tag.name$all, $any, $nonestring[]Filter by tag names
category.id$all, $any, $noneinteger[]Filter by Newsroom Categories ids
category.slug$all, $any, $nonestring[]Filter by Newsroom Categories slugs
published_at$gt , $ge , $lt , $leISO8601 datetime stringFilter by publication date
scheduled_at$gt , $ge , $lt , $leISO8601 datetime stringFilter by scheduled date
updated_at$gt, $ge, $lt, $leISO8601 datetime stringFilter by last modification date
header_image$eq, $nenullFilter by having or not having header image by comparing to null.
preview_image$eq, $nenullFilter by having or not having preview image by comparing to null .
social_image$eq , $nenullFilter by having or not having social image by comparing to null .
images.count$gt , $ge , $lt , $leintegerFilter by number of attached images.
videos.count$gt , $ge , $lt , $leintegerFilter by number of attached videos.

Personal access tokens: stories:read. Every listed scope is required; the token owner's permissions, feature availability and newsroom access still apply.

Authorization

API_key
headerAuthorizationBearer <token>

Bearer authentication using an integration API key, or a personal access token only where the operation explicitly supports it. Every listed personal-token scope is required; owner permissions and newsroom access still apply.

Header Parameters

Accept?string

Use the content-format field to request a conversion

Matchapplication/json; [content-format=(v1|v3|v4|v5|v6)]
Default"application/json"

Request Body

Example for the scope parameter:

{  "$and": [    {      "status": {        "$in": ["published"]      }    },    {      "newsroom.uuid": {        "$in": ["{SITE_UUID}"]      }    }  ]}

Example for the query parameter:

{  "$and": [    {      "published_at": {        "$ge": "2023-03-15T11:00:00.000Z"      }    },    {      "language": {        "$in": ["en", "de"]      }    }  ]}
application/json
  1. body

Search params

limit?Pagination Limit

Max number of records to fetch.

offset?Pagination Offset

Pagination offset.

sort?Sort Order

Sort order to return records in.

Match[+-]?(\w+\.)*\w+
query?

A query object following our Prezly Query Language syntax.

include?string

Comma-separate list of additional optional fields to include.

See Stories List API documentation for details.

scope?

A query object following our Prezly Query Language syntax.

Response Body

OK

application/json
  1. response
stories?array<>
pagination?
sort?Sort Order

Sort order to return records in.

Match[+-]?(\w+\.)*\w+
Example Request
curl -X POST 'https://api.prezly.com/v2/stories/search' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response200
{  "stories": [    {      "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",      "id": 0,      "thumbnail_url": "http://example.com",      "title": "string",      "subtitle": "string",      "intro": "string",      "culture": [        {          "code": "en",          "name": "string",          "direction": "ltr",          "language_code": "en",          "native_name": "string"        }      ],      "format_version": 1,      "slug": "string",      "language": "string",      "status": "uninitialized",      "lifecycle_status": "uninitialized",      "publication_status": "uninitialized",      "visibility": "private",      "is_archived": true,      "is_finalized": true,      "is_published": true,      "is_draft": true,      "is_embargo": true,      "is_private": true,      "is_scheduled": true,      "is_analytics_available": true,      "is_sharable": true,      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z",      "published_at": "2019-08-24T14:15:22Z",      "scheduled_at": "2019-08-24T14:15:22Z",      "author": {        "id": 0,        "email": "http://example.com",        "name": "string",        "display_name": "string",        "first_name": "string",        "last_name": "string",        "avatar_url": "http://example.com"      },      "newsroom": {        "id": 0,        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",        "name": "string",        "display_name": "string",        "subdomain": "string",        "thumbnail_url": "http://example.com",        "timezone": "europe/london",        "is_active": true,        "is_archived": true,        "is_online": true,        "is_offline": true,        "is_multilingual": true,        "url": "http://example.com",        "links": {          "media_gallery_api": "http://example.com",          "room_contacts_api": "http://example.com",          "analytics_and_visibility_settings": "http://example.com",          "categories_management": "http://example.com",          "company_info_settings": "http://example.com",          "contacts_management": "http://example.com",          "domain_settings": "http://example.com",          "edit": "http://example.com",          "gallery_management": "http://example.com",          "hub_settings": "http://example.com",          "languages": "http://example.com",          "look_and_feel_settings": "http://example.com",          "manual_subscription_management": "http://example.com",          "privacy_settings": "http://example.com",          "widget_settings": "http://example.com"        }      },      "oembed": {        "url": "http://example.com",        "type": "video",        "version": "1.0",        "title": "string",        "description": "string",        "author_name": "string",        "author_url": "http://example.com",        "provider_name": "string",        "provider_url": "http://example.com",        "cache_age": 0,        "html": "string",        "thumbnail_url": "http://example.com",        "thumbnail_width": 1,        "thumbnail_height": 1,        "screenshot_url": "http://example.com"      },      "links": {        "api": "string",        "preview": "string",        "edit": "string",        "sharing": "string",        "duplicate": "string",        "translate": "string",        "analytics": "string",        "delete": "string",        "publication_api": "string",        "reports_api": "string",        "short": "string",        "newsroom_view": "http://example.com",        "newsroom_preview": "http://example.com"      },      "categories": [        {          "id": 0,          "display_name": "string",          "display_description": "string",          "i18n": {            "[a-z]{2,3}(_[A-Z][a-z]{3})?(_[A-Z]{2})?": {              "name": "string",              "description": "string",              "slug": "string",              "locale": {                "code": "en",                "name": "string",                "direction": "ltr",                "language_code": "en",                "native_name": "string"              }            }          },          "stories_number": 0        }      ],      "translations": [        {          "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",          "id": 0,          "thumbnail_url": "http://example.com",          "title": "string",          "culture": {            "code": "en",            "name": "string",            "direction": "ltr",            "language_code": "en",            "native_name": "string"          },          "language": "string",          "status": "uninitialized",          "lifecycle_status": "uninitialized",          "publication_status": "uninitialized",          "visibility": "public",          "created_at": "2019-08-24T14:15:22Z",          "updated_at": "2019-08-24T14:15:22Z",          "published_at": "2019-08-24T14:15:22Z",          "scheduled_at": "2019-08-24T14:15:22Z",          "author": {            "id": 0,            "email": "http://example.com",            "name": "string",            "display_name": "string",            "first_name": "string",            "last_name": "string",            "avatar_url": "http://example.com"          },          "newsroom": {            "id": 0,            "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",            "name": "string",            "display_name": "string",            "subdomain": "string",            "thumbnail_url": "http://example.com",            "timezone": "europe/london",            "is_active": true,            "is_archived": true,            "is_online": true,            "is_offline": true,            "is_multilingual": true,            "url": "http://example.com",            "links": {              "media_gallery_api": "http://example.com",              "room_contacts_api": "http://example.com",              "analytics_and_visibility_settings": "http://example.com",              "categories_management": "http://example.com",              "company_info_settings": "http://example.com",              "contacts_management": "http://example.com",              "domain_settings": "http://example.com",              "edit": "http://example.com",              "gallery_management": "http://example.com",              "hub_settings": "http://example.com",              "languages": "http://example.com",              "look_and_feel_settings": "http://example.com",              "manual_subscription_management": "http://example.com",              "privacy_settings": "http://example.com",              "widget_settings": "http://example.com"            }          },          "url": "http://example.com",          "oembed": {            "url": "http://example.com",            "type": "video",            "version": "1.0",            "title": "string",            "description": "string",            "author_name": "string",            "author_url": "http://example.com",            "provider_name": "string",            "provider_url": "http://example.com",            "cache_age": 0,            "html": "string",            "thumbnail_url": "http://example.com",            "thumbnail_width": 1,            "thumbnail_height": 1,            "screenshot_url": "http://example.com"          },          "slug": "string"        }      ],      "coverage_number": 0,      "images_number": 0,      "videos_number": 0,      "last_coverage_at": "2019-08-24T14:15:22Z",      "content_version": 0    }  ],  "pagination": {    "offset": 0,    "limit": 0,    "matched_records_number": 0,    "total_records_number": 0  },  "sort": "+display_name"}

Get Story Translation Suggestions GET

Read saved translation candidates when the account has access to the suggestions feature.

Create Story POST

Create a story in a newsroom. Content starts as a draft; publishing is a separate action.