Create a swift collection - Fluid Topics

This web service creates a new swift collection and adds it to the user's library.

Method	Endpoint
`POST`	`/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.

Request example

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

{
  "title": "My new swift collection",
  "description": "A swift collection of topics about xyz",
  "color": "green",
  "searchRequest": {
    "query": "xyz",
    "metadataFilters": [
      {
        "key": "Category",
        "label": "Category",
        "rangeFilter": {
          "from": "2022-07-08",
          "to": "2022-10-13"
        }
      },
      {
        "key": "ft:editorialType",
        "label": "ft:editorialType",
        "valueFilter": {
          "values": [
            "book"
          ],
          "negative": false
        }
      }
    ],
    "contentLocale": "en-US",
    "sort": [
      {
        "key": "afs:sort=versionFacet",
        "order": "DESC",
        "type": "NATURAL"
      }
    ]
  }
}

Field	Type	Required?	Description
`title`	String	Yes	A name for the swift collection.
`description`	String	Yes	A description of the swift collection.
`color`	String	Yes	A color for the swift collection's tag. Accepted values are `black`, `green`, `blue`, `purple`, `red`, `orange`, and `yellow`.
`alert`	Boolean	No	A boolean indicating whether to activate an alert for the search. Possible values are `true` or `false`.
`searchRequest`	Object	Yes	The parameters of the search corresponding to the swift collection.
`contentLocale`	String	Yes	Defines 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	An element prefixed by `afs:sort` that defines additional criteria by which to sort search results.
`order`	String	No	An element that defines the sort order. Possible values are `ASC` and `DESC`.
`type`	String	No	The sorting method to be applied to search results. Possible values are `ALPHA` (lexicographic order) and `NATURAL` (natural sort order).

Response body

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

{
  "ownerId": "d433cb2q-8d2f-4aaf-a8fc-917e154b4ceb",
  "id": "bf93cb2q-3070-4aaf-a134-917e154b4ceef",
  "title": "My new swift collection",
  "description": "A 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": "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"
      }
    }
  },
  "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	Defines 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.

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

Create a swift collection - Fluid Topics - Latest

Fluid Topics API Reference Guide