Update a swift collection - Fluid Topics

This web service updates a swift collection that was previously added to the user's library.

Method	Endpoint
`PUT`	`/api/users/{userId}/collections/{collectionId}`

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.
`{collectionId}`	String	The identifier of the collection as retrieved when listing collections.

The title, description, color, and searchRequest parameters are optional, but it is necessary to specify at least one.
Only parameters included in the query are updated. Parameters not included in the query remain unchanged.

Request example

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

{
  "title": "My updated swift collection",
  "description": "An updated swift collection of topics about xyz",
  "color": "green",
  "searchRequest": {
    "contentLocale": "en-US",
    "query": "xyz",
    "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"
      }
    ]
  }
}

Field	Type	Required?	Description
`title`	String	No	A name for the swift collection.
`description`	String	No	A description of the swift collection.
`color`	String	No	A color for the swift collection's tag. Accepted values are `black`, `green`, `blue`, `purple`, `red`, `orange`, and `yellow`.
`searchRequest`	Object	No	The parameters of the search corresponding to the swift collection.
`contentLocale`	String	Yes	Indicates the language of the search results.
`query`	String	No	The keywords of the query.
`metadataFilters`	Array	No	Filters the results based on selected criteria including metadata and date ranges. Defaults to an empty list.
`key`	String	Yes	Expects a metadata key.
`valueFilter`	Object	No	Contains the filtering conditions based on metadata values.
`values`	Array	Yes	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	No	When `true`, this parameter excludes results matching the previously defined values. By default, the `negative` parameter is implicit and `false`.
`dateFilter`	Object	No	Specifies the date-based filtering conditions using predefined periods.
`type`	String	Yes	Restricts results to those within a predefined period. Acceptable values are `LAST_WEEK`, `LAST_MONTH`, `LAST_QUARTER`, `LAST_YEAR`.
`rangeFilter`	Object	No	Specifies custom date range filtering.
`from`	String	Yes	The inclusive start date of the period. If unspecified, the default value is `1970-01-01`.
`to`	String	Yes	The inclusive end date of the period. If unspecified, the default value is the current day.
`sort`	Array	No	An optional element of the `searchRequest` parameter defining whether search results should be sorted based on certain criteria.
`key`	String	No	A parameter prefixed by `afs:sort` that defines additional criteria by which to sort search results.
`order`	String	No	Defines the sort order. Possible values are `ASC` and `DESC`.
`type`	String	Yes	The sorting method to be applied to search results. Possible values are `ALPHA` (lexicographic order) and `NATURAL` (natural sort order).

Return code	Description
`20O OK`	The collection was updated.
`400 BAD REQUEST`	A required parameter is missing or an invalid color was provided for the collection's tag.
`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, the identifier for the `documents` parameter does not correspond to an existing document or no collection matches the `COLLECTION_ID`.

The title, description, color, and searchRequest parameters are optional, but it is necessary to specify at least one.
Only fields included in the request body are updated. Fields not included in the request body remain the same.

Response body

{
  "ownerId": "d433cb2q-8d2f-4aaf-a8fc-917e154b4ceb",
  "id": "bf93cb2q-3070-4aaf-a134-917e154b4ceef",
  "title": "My updated swift collection",
  "description": "An updated swift collection of topics about xyz",
  "color": "green",
  "searchRequest": {
    "contentLocale": "en-US",
    "query": "xyz",
    "filters": [
      {
        "key": "ft:editorialType",
        "label": "ft:editorialType",
        "values": [
          "book"
        ],
        "negative": false
      }
    ],
    "metadataFilters": [
      {
        "key": "ft:editorialType",
        "valueFilter": {
          "values": [
            "book"
          ],
          "negative": false
        }
      },
      {
        "key": "Category",
        "rangeFilter": {
          "from": "2022-07-08",
          "to": "2023-10-13"
        }
      }
    ],
    "sort": [
      {
        "type": "NATURAL",
        "key": "afs:sort=versionFacet",
        "order": "DESC"
      }
    ],
    "periodFilter": {
      "key": "Category",
      "periodType": "CUSTOM",
      "period": {
        "from": "2022-07-08",
        "to": "2022-10-13"
      }
    }
  },
  "documentsUrl": "https://doc.fluidtopics.com/api/users/{userId}/collections/{collectionId}/documents",
  "creationDate": "2023-10-22T15:10:07.126+00:00",
  "lastUpdate": "2023-10-22T15:10:07.126+00:00"
}

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.
`color`	String	The color of the collection's tag.
`searchRequest`	Object	The parameters of the search corresponding to the swift collection.
`contentLocale`	String	Indicates the language of the search results.
`query`	String	The keywords of the query.
`filters`	Array	The filters applied to the search query.
`key`	String	The filter's metadata key.
`values`	Array	A list of values for the metadata key.
`metadataFilters`	Array	Filters applied to the search query based on metadata values and date ranges.
`key`	String	The filter's metadata key.
`valueFilter`	Object	Contains conditions based on metadata values.
`values`	Array	A list of values for the metadata key.
`negative`	Boolean	Excludes results matching the specified `values` when `true`. Defaults to `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 start date of the period used to filter the search results.
`to`	String	The end date of the period used to filter the search results.
`sort`	Array	Indicates if search results should be sorted based on certain criteria.
`key`	String	An element prefixed by `afs:sort` that defines additional criteria by which to sort search results.
`order`	String	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`	Object	Filters search results by period.
`key`	String	The filter's metadata key.
`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`	Object	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.
`documentsUrl`	String	A URL to retrieve the list of documents in 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.

If the request body does not include the searchRequest parameter, neither will the output.

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

Update a swift collection - Fluid Topics - Latest

Fluid Topics API Reference Guide