List collections - Fluid Topics - Latest

Fluid Topics API Reference Guide
Category
Reference Guides
Audience
public
Version
Latest

This web service lists all collections that were previously added to the user's library.

Method Endpoint
GET 
/api/users/{userId}/collections
Path parameter Type Description
{userId} String The user's identifier. See the List users or Search users web services to find a user's ID.

Response body

The following lines show an example of a JSON response body:

[
  {
    "ownerId": "24502ba6-a2da-4db8-8ec1-c8d29f970454",
    "id": "a393cb2q-3070-4aaf-a134-917e154b4ceb",
    "title": "Collection number one",
    "description": "A collection of topics about xyz",
    "creationDate": "2023-10-22T15:10:07.126+00:00",
    "lastUpdate": "2023-11-09T11:54:03.121+00:00",
    "color": "orange",
    "documentsUrl": "https://doc.fluidtopics.com/api/users/{userId}/collections/{collectionId}/documents"
  },
  {
    "ownerId": "87532-gt4g-3fn6-9gh2-b1d29h377422",
    "id": "g177gs2a-4199-4bts-n611-301360ab1arv",
    "title": "Collection number two",
    "description": "A collection of topics about abc",
    "creationDate": "2023-10-22T15:10:07.126+00:00",
    "lastUpdate": "2023-11-09T11:54:03.121+00:00",
    "color": "orange",
    "searchRequest": {
      "contentLocale": "en-US",
      "query": "abc",
      "filters": [
        {
          "key": "ft:editorialType",
          "values": [
            "book"
          ],
          "negative": false
        }
      ],
      "metadataFilters": [
        {
          "key": "ft:editorialType",
          "valueFilter": {
            "values": [
              "book"
            ],
            "negative": false
          }
        },
        {
          "key": "Category",
          "rangeFilter": {
            "from": "2022-07-08",
            "to": "2022-10-13"
          }
        }
      ],
      "sort": [
        {
          "type": "NATURAL",
          "key": "afs:sort=versionFacet",
          "order": "DESC"
        }
      ],
      "periodFilter": {
        "key": "period",
        "periodType": "CUSTOM",
        "period": {
          "from": "2022-07-08",
          "to": "2022-10-13"
        }
      }
    }
  }
]
Field Type Description
ownerId String The identifier of the user who owns the collection.
id String The identifier of the collection.
title String The name of the collection.
description String The description of the collection.
creationDate String The date and time when the collection was created.
lastUpdate String The date and time when the collection was last updated.
documentsUrl String A URL to retrieve the list of documents in the collection.
color String A color for the collection's tag. Accepted values are black, green, blue, purple, red, orange, and yellow.
searchRequest Object The parameters of the search (for swift collections only).
contentLocale String Indicates the language of the search results.
query String The terms of the search query.
filters Array The filters applied to the search query.
key String The filter's metadata key.
values String A list of values for the metadata key.
metadataFilters Array Filters the results based on selected criteria including metadata and date ranges. Defaults to an empty list.
key String Expects a metadata key.
valueFilter Object Contains the filtering conditions based on metadata values.
values Array Defines the value for the selected key. When multiple values are defined, they are combined with an AND or an OR operator depending on the tenant's configuration.
negative Boolean When true, this parameter excludes results matching the previously defined values. By default, the negative parameter is implicit and false.
dateFilter Object Specifies the date-based filtering conditions using predefined periods.
type String Restricts results to those within a predefined period. Acceptable values are LAST_WEEK, LAST_MONTH, LAST_QUARTER, LAST_YEAR.
rangeFilter Object Specifies custom date range filtering.
from String The inclusive start date of the period. If unspecified, the default value is 1970-01-01.
to String The inclusive end date of the period. If unspecified, the default value is the current day.
sort Array Indicates if search results are sorted based on certain criteria.
key String A parameter prefixed by afs:sort that defines additional criteria by which to sort search results.
order Boolean Defines the sort order. Possible values are ASC and DESC.
type String The sorting method to be applied to search results. Possible values are ALPHA (lexicographic order) and NATURAL (natural sort order).
periodFilter Array Filters search results by period.
periodType String Defines the type of period by which to filter the search results. Possible values include LAST_WEEK, LAST_MONTH, LAST_YEAR and CUSTOM.
period Array Defines the period by which to filter the search results.
from String The start date of the period.
to String The end date of the period.

The filters and periodFilter arrays are deprecated. Use the metadataFilters array instead. It combines the values of both arrays.

Selecting the URL in the documentsUrl section sends a GET request to list information about each document. This includes URLs to access collection documents in the Reader page.

Return code Description
200 OK The request is valid and returns data.
401 UNAUTHORIZED The authorization header is absent or invalid.
403 FORBIDDEN The user or API key does not have the USERS_ADMIN or ADMIN role, or the user corresponding to the USER_ID parameter does not have the COLLECTION_USER role.
404 NOT FOUND No user exists with this ID.