Based on REST principles, the TrendMiner Work Organizer API endpoints provide access to all work created and saved by users like views, searches, formulas, etc.

1. Authentication

All requests to the web API require authentication. This is achieved by sending a valid Bearer access token in the request headers. Request tokens are obtained using OAuth2.0.

Requests to the Work Organizer API can be done authenticated as your client. To do requests, you first need to create a client and request a token.

When you create/update saved items authenticated as your client, they will belong to service-account-CLIENTID.

Make sure you are calling our services over HTTPS when retrieving an access token.

1.1. Creating a new client

A new client can be created in ConfigHub: Security → Clients → Add client

1.2. Retrieving an access token

To retrieve a token to authenticate as your client, you will need:

  • Your client ID

  • Your client secret (can be obtained in ConfigHub)

A token is requested from the token endpoint of the authentication service:

Request
curl --request POST \
  --url 'https://YOUR_DOMAIN/auth/realms/trendminer/protocol/openid-connect/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=YOUR_CLIENT_ID \
  --data client_secret=YOUR_CLIENT_SECRET

Upon valid authentication, the response will contain an access token.

Response
200 OK
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJwcXZ1UXB...", (1)
  "expires_in": 300,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 1571391000,
  "scope": "email profile"
}

  1. The access token is to be used in every request towards our services (see example below). A new token needs to be fetched when the token expires after 5 minutes.

1.3. Doing a request with an access token

Example request with access token
curl --request GET \
  --url 'https://YOUR_DOMAIN/work/[any-api]' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --header 'Authorization: Bearer ACCESS_TOKEN'

2. Resources

2.1. AccessRules

2.1.1. Create an access rule for the saved item.

POST /saveditem/{savedItemId}/accessrule

Parameters

Type

Name

Description

Schema

Path required

savedItemId

The saved item for which to create the access rule

String

Body

required

SavedItemAccessRuleModel

The access rule model.

SavedItemAccessRuleModel
Responses

HTTP Code

Description

Schema

401

Unauthorized

AccessRuleResource

404

The resource was not found

AccessRuleResource

201

Created

AccessRuleResource

400

Validation failed

AccessRuleResource
Produces

  • application/json

2.1.2. Delete an access rule for a saved item

DELETE /saveditem/{savedItemId}/accessrule/{accessRuleId}

Parameters

Type

Name

Description

Schema

Path required

savedItemId

The saved item to which the access rule apply

String

Path required

accessRuleId

The identifier of the access rule to delete

UUID
Responses

HTTP Code

Description

Schema

401

Unauthorized

String

404

The resource was not found

String

204

No response

String

400

Validation failed

String
Produces

  • application/json

2.1.3. Get the access rules for a saved item.

GET /saveditem/{savedItemId}/accessrule

Parameters

Type

Name

Description

Schema

Path required

savedItemId

The saved item to which the access rules apply

String
Responses

HTTP Code

Description

Schema

401

Unauthorized

List[AccessRuleResource]

404

The resource was not found

List[AccessRuleResource]

400

Validation failed

List[AccessRuleResource]

200

OK

List[AccessRuleResource]
Produces

  • application/json

2.2. Permissions

2.2.1. Returns a list of permissions for the saved item for the current logged in user

GET /permissions

Parameters

Type

Name

Description

Schema

Query

optional

saved-item-identifier

The identifier of the saved item to fetch permissions.This can be omitted for complex-item-identifier.

Query

optional

complex-item-identifier

The external identifier of the complex item to fetch permissions. This will be ignored if saved-item-identifier is present.
Responses

HTTP Code

Description

Schema

403

Forbidden

PermissionsResource

200

Ok

PermissionsResource

404

Resource not found

PermissionsResource
Produces

  • application/json

2.3. Preferences

2.3.1. Create a new preference

POST /preferences

Parameters

Type

Name

Description

Schema

Body

required

PreferenceModel

A representation of a preference with name and data to create

PreferenceModel
Responses

HTTP Code

Description

Schema

401

Unauthorized

PreferenceResource

201

Created

PreferenceResource

400

Validation failed

PreferenceResource
Produces

  • application/json

2.3.2. Delete an existing preference for the logged in user

DELETE /preferences/{name}

Parameters

Type

Name

Description

Schema

Path required

name

The name of an existing preference to delete

String
Responses

HTTP Code

Description

Schema

401

Unauthorized

String

404

Resource(s) not found!

String

405

Method Not Allowed

String

204

No response

String

400

Validation failed

String
Produces

  • application/json

2.3.3. Retrieve an existing preference for the logged in user

GET /preferences/{name}

Parameters

Type

Name

Description

Schema

Path required

name

The name of an existing preference to retrieve

String
Responses

HTTP Code

Description

Schema

401

Unauthorized

PreferenceResource

404

Resource(s) not found!

PreferenceResource

200

Ok

PreferenceResource
Produces

  • application/json

2.3.4. Retrieve all preferences for the logged in user

GET /preferences

Parameters
Type Name Description Schema
Responses

HTTP Code

Description

Schema

401

Unauthorized

List[PreferenceResource]

200

Ok

List[PreferenceResource]
Produces

  • application/json

2.3.5. Store a list of preferences

POST /preferences/store

Parameters

Type

Name

Description

Schema

Body

required

PreferenceModel

A list of preferences to store

PreferenceModel
Responses

HTTP Code

Description

Schema

401

Unauthorized

List[PreferenceResource]

400

Validation failed

List[PreferenceResource]

200

Ok

List[PreferenceResource]
Produces

  • application/json

2.3.6. Update a preference

PUT /preferences/{name}

Parameters

Type

Name

Description

Schema

Path required

name

The name of an existing preference to update

String

Body

required

PreferenceModel

A representation of a preference with data to update.<br> The name in this model will be ignored.

PreferenceModel
Responses

HTTP Code

Description

Schema

401

Unauthorized

PreferenceResource

404

Resource(s) not found!

PreferenceResource

405

Method Not Allowed

PreferenceResource

400

Validation failed

PreferenceResource

200

Ok

PreferenceResource
Produces

  • application/json

2.4. SavedItemTypes

2.4.1. Retrieves the details of the specified type

GET /saveditemtype/{id}

Parameters

Type

Name

Description

Schema

Path required

id

The name of the saved item type to retrieve details of

String
Responses

HTTP Code

Description

Schema

200

OK

SavedItemTypeResource
Produces

  • application/hal+json

  • application/x-spring-data-compact+json

2.4.2. List all the available saved item types

GET /saveditemtype

Parameters
Type Name Description Schema
Responses

HTTP Code

Description

Schema

200

OK

CollectionModelSavedItemTypeResource
Produces

  • application/hal+json

  • application/x-spring-data-compact+json

2.5. SavedItems

2.5.1. Browse the contents of a folder

GET /saveditem/browse

Parameters

Type

Name

Description

Schema

Query

optional

parent

The identifier of the folder you want to browse

Query

optional

excludeTypes

A list of saved item types.<br/>These types will be excluded from the result.

Query

optional

includeTypes

A list of saved item types.<br/>The result will only contain these types.

Query

optional

includeData

Set to true to include the full data object in the result.<br/>Defaults to false

Query

optional

foldersOnly

Set to true to only return folders.

Query

optional

page

Zero-based page index (0..N)

Query

optional

size

The size of the page to be returned

Query

optional

sort

Sorting criteria in the format: property(,asc

desc). Default sort order is ascending. Multiple sort criteria are supported.
Responses

HTTP Code

Description

Schema

404

The resource was not found!

PagedModelSavedItemResource

400

Validation failed

PagedModelSavedItemResource

200

Ok

PagedModelSavedItemResource
Produces

  • application/hal+json

  • application/x-spring-data-compact+json

2.5.2. Copy an existing saved item.

POST /saveditem/{id}/copy

Parameters

Type

Name

Description

Schema

Path required

id

The identifier of the existing saved item that will be copied

String

Body

required

SavedItemModel

The API model containing the changes to apply to the copied saved item.<br/>Only the name and/or description can be changed

SavedItemModel
Responses

HTTP Code

Description

Schema

403

Forbidden

SavedItemResource

404

The resource was not found!

SavedItemResource

201

Created

SavedItemResource

400

Validation failed

SavedItemResource
Produces

  • application/hal+json

  • application/x-spring-data-compact+json

2.5.3. Create a new saved item

POST /saveditem

Parameters

Type

Name

Description

Schema

Body

required

SavedItemModel

A model of the item to create

SavedItemModel
Responses

HTTP Code

Description

Schema

201

Created

SavedItemResource

400

Validation failed

SavedItemResource
Produces

  • application/hal+json

  • application/x-spring-data-compact+json

2.5.4. Delete saved item(s)

DELETE /saveditem/{id}

Parameters

Type

Name

Description

Schema

Path required

id

The id's of the saved items to delete

String
Responses

HTTP Code

Description

Schema

404

The resource was not found!

DeletedItemsResource

200

OK

DeletedItemsResource
Produces

  • application/hal+json

  • application/x-spring-data-compact+json

2.5.5. Retrieve a saved item

GET /saveditem/{id}

Parameters

Type

Name

Description

Schema

Path required

id

The identifier of the saved item to retrieve.<br/>This identifier should be a valid UUID.

String
Responses

HTTP Code

Description

Schema

404

Resource(s) not found!

SavedItemResource

403

Forbidden

SavedItemResource

200

Ok

SavedItemResource
Produces

  • application/hal+json

  • application/x-spring-data-compact+json

2.5.6. Move saved item(s) to a folder

PUT /saveditem/{id}/move

Parameters

Type

Name

Description

Schema

Path required

id

List

Path required

itemsToMove

The identifier(s) of the saved item(s) to move.

String

Query

optional

destination

The identifier of the destination folder.
Responses

HTTP Code

Description

Schema

204

Ok

Object

404

The resource was not found!

Object

406

Duplicate item!

Folder structure invalid!
Produces

  • application/hal+json

  • application/x-spring-data-compact+json

2.5.7. Patch a saved item

PATCH /saveditem/{id}

Parameters

Type

Name

Description

Schema

Path required

id

The identifier of the saved item that will be patched

String

Body

required

SavedItemModel

The API model containing the changes to apply to the saved item. Only the extended view properties are checked and the rest will be ignored

SavedItemModel
Responses

HTTP Code

Description

Schema

404

The resource was not found!

SavedItemResource

400

Validation failed

SavedItemResource

200

Ok

SavedItemResource

406

Duplicate item!

Folder structure invalid!
Produces

  • application/hal+json

  • application/x-spring-data-compact+json

2.5.8. Search saved items

GET /saveditem/search

Parameters

Type

Name

Description

Schema

Query

required

query

A query string to search.<br/>Only the name and description of the saved item are search.<br/>Wildcards (*) are supported on all locations.

Query

optional

excludeTypes

A list of saved item types.<br/>These types will be excluded from the result.

Query

optional

includeTypes

A list of saved item types.<br/>The result will only contain these types.

Query

optional

includeData

Set to true to include the full data object in the result.<br/>Defaults to false

Query

optional

sharedWithMe

Set to true to filter the results to only show items that are shared with the logged in user.<br/>Defaults to false

Query

optional

page

Zero-based page index (0..N)

Query

optional

size

The size of the page to be returned

Query

optional

sort

Sorting criteria in the format: property(,asc

desc). Default sort order is ascending. Multiple sort criteria are supported.
Responses

HTTP Code

Description

Schema

400

Validation failed

PagedModelSavedItemResource

200

Ok

PagedModelSavedItemResource
Produces

  • application/hal+json

  • application/x-spring-data-compact+json

2.5.9. Update a saved item

PUT /saveditem/{id}

Parameters

Type

Name

Description

Schema

Path required

id

The identifier of the saved item that will be updated

String

Body

required

SavedItemModel

The API model containing the changes to apply to the saved item.

SavedItemModel
Responses

HTTP Code

Description

Schema

404

The resource was not found!

SavedItemResource

400

Validation failed

SavedItemResource

200

Ok

SavedItemResource

406

Duplicate item!

Folder structure invalid!
Produces

  • application/hal+json

  • application/x-spring-data-compact+json

2.6. SavedItemsDemo

2.6.1. Create demo saved items for a (new) user

POST /saveditem/demo

Parameters

Type

Name

Description

Schema

Body

required

UserInformationModel

UserInformationModel
Responses

HTTP Code

Description

Schema

201

Created

Object

400

Validation failed

Object
Produces

  • application/hal+json

  • application/x-spring-data-compact+json

2.7. SavedItemsExportImport

2.7.1. Export saved items

GET /export

Parameters

Type

Name

Description

Schema

Query

optional

username

The username for which the savedItems need to be exported (default: current user)
Responses

HTTP Code

Description

Schema

403

Forbidden

Object

200

Ok

Object
Produces

  • /

2.7.2. Retrieve the results from the current or last import

GET /import/result

Parameters
Type Name Description Schema
Responses

HTTP Code

Description

Schema

200

Ok

ImportResult
Produces

  • /

2.7.3. Import saved items

POST /import

Parameters

Type

Name

Description

Schema

Query

optional

username

The username for which the savedItems need to be imported (default: current user)

Query

optional

skip

when set to true, duplicates will not be imported; when set to false, duplicates will be replaced (default: true)
Responses

HTTP Code

Description

Schema

403

Forbidden

ImportResult

200

Ok

ImportResult
Produces

  • /

2.8. Sessions

2.8.1. Create a new session

POST /sessions

Parameters

Type

Name

Description

Schema

Body

required

SessionModel

A session containing valid JSON data

SessionModel
Responses

HTTP Code

Description

Schema

401

Unauthorized

PreferenceResource

201

Created

PreferenceResource

400

Validation failed

PreferenceResource
Produces

  • application/json

2.8.2. Delete an existing session

DELETE /sessions/{identifier}

Parameters

Type

Name

Description

Schema

Path required

identifier

The short url identifier of the session to delete

String
Responses

HTTP Code

Description

Schema

401

Unauthorized

Object

404

Resource(s) not found!

Object

405

Method Not Allowed

Object

204

No response

Object

400

Validation failed

Object
Produces

  • application/json

2.8.3. Retrieve a session

GET /sessions/{identifier}

Parameters

Type

Name

Description

Schema

Path required

identifier

The short url identifier of the session to retrieve

String
Responses

HTTP Code

Description

Schema

401

Unauthorized

PreferenceResource

404

Resource(s) not found!

PreferenceResource

200

Ok

PreferenceResource
Produces

  • application/json

2.8.4. Get a session by viewId

GET /sessions

Parameters

Type

Name

Description

Schema

Query

required

viewId

The viewId of the session
Responses

HTTP Code

Description

Schema

401

Unauthorized

PreferenceResource

404

Resource(s) not found!

PreferenceResource

200

Ok

PreferenceResource
Produces

  • application/json

3. Models

3.1. AccessRuleResource

Represents an access rule definition

Field Name Required Type Description Format

identifier

String

The identifier of the access rule.

objectId

X

String

The identifier of the object.

paths

X

List of [string]

An array of paths towards the object.

subjectId

X

String

The identifier of the subject.

subjectType

X

String

The type of the subject: USER, GROUP, EVERYBODY, GUEST.

Enum: GUEST, EVERYONE, GROUP, USER,

permissions

X

Set of [string]

A set of permissions the subject has on the specified object. Can be an empty set.

Enum:

userDetailsResource

UserDetailsResource

_links

Map of Link

3.2. CollectionModelSavedItemTypeResource

Field Name Required Type Description Format

_embedded

CollectionModelSavedItemTypeResource__embedded

_links

Map of Link

3.3. CollectionModelSavedItemTypeResourceEmbedded

Field Name Required Type Description Format

savedItemTypeResourceList

List of SavedItemTypeResource

3.4. DeletedItemsResource

Object to describe the saved items that were deleted

Field Name Required Type Description Format

identifiers

List of [string]

The identifiers of the deleted items

_links

Map of Link

3.5. ImportFailure

Field Name Required Type Description Format

fileLocation

String

typeOfFailure

String

message

String

itemIdentifier

String

itemName

String

itemType

String

itemLocation

List of [string]

3.6. ImportResult

Field Name Required Type Description Format

identifier

UUID

uuid

inProgress

Boolean

startTime

String

endTime

String

severeFailure

ImportFailure

totalOfItemsSuccessfullyImported

Integer

int32

totalOfItemsFailedToImport

Integer

int32

totalOfSkippedItems

Integer

int32

totalOfReplacedItems

Integer

int32

failureDetails

List of ImportFailure

itemsSkipped

List of [string]

itemsReplaced

List of [string]
Field Name Required Type Description Format

href

String

hreflang

String

title

String

type

String

deprecation

String

profile

String

name

String

templated

Boolean

3.8. PageMetadata

Field Name Required Type Description Format

size

Long

int64

totalElements

Long

int64

totalPages

Long

int64

number

Long

int64

3.9. PagedModelSavedItemResource

Field Name Required Type Description Format

_embedded

PagedModelSavedItemResource__embedded

_links

Map of Link

page

PageMetadata

3.10. PagedModelSavedItemResourceEmbedded

Field Name Required Type Description Format

content

List of SavedItemResource

3.11. PermissionsResource

Describes a list of permissions

Field Name Required Type Description Format

permissions

List of [string]

The list of permissions

_links

Map of Link

3.12. PreferenceModel

API model of a preference

Field Name Required Type Description Format

name

X

String

A unique name for the preference

data

X

Object

JSON object containing the definition of the preference

3.13. PreferenceResource

Represents a saved user preference

Field Name Required Type Description Format

name

String

The name of the preference

data

Object

JSON object containing the definition of the preference

_links

Map of Link

3.14. SavedItemAccessRuleModel

API model for an access rule on a SavedItem

Field Name Required Type Description Format

subjectId

String

The identifier of the subject for which to grant the access rule

subjectType

X

String

The type of the subject

Enum: GUEST, EVERYONE, GROUP, USER,

permissions

X

Set of [string]

The set of permissions

Enum:

autoGenerated

Boolean

3.15. SavedItemModel

API model for creation or modification of a saved item

Field Name Required Type Description Format

id

String

The identifier of the saved item.<br/>This identifier is a UUID.

parentId

String

The UUID of the folder where this saved item can be found.<br/>This folder is a saved item.<br/>When empty, the saved item will be saved in the most top level.

type

String

The type of the saved item.<br/>The type indicates what can be stored in the data property.

Enum: SIMILARITY_SEARCH, VALUE_BASED_SEARCH, CROSS_ASSET_VALUE_BASED_SEARCH, DIGITAL_STEP_SEARCH, AREA_SEARCH, FINGERPRINT, LEGACY_FINGERPRINT, VIEW, TREND_HUB_2_VIEW, FILTER, CONTEXT_LOGBOOK_VIEW, FORMULA, AGGREGATION, DASHBOARD, MONITOR, MACHINE_LEARNING, PREDICTIVE, TOTALIZER, NOTEBOOK, PIPELINE,

name

X

String

The name of the savedItem

description

String

The description of the savedItem

data

Map of [object]

A Json Object representing the content of the saved item.<br/>This content is specific to the saved item type.

extendedViewProperties

Map of [string]

Key value pairs representing the extended view properties of the saved item.<br/>This content is specific to the saved item type.

folder

Boolean

true if the saved item is a folder; false otherwise.<br/>A folder can not contain data nor a type.<br/>As a result, both the data and type property will be ignored when a folder is saved.

3.16. SavedItemResource

The definition of a saved item

Field Name Required Type Description Format

identifier

String

The identifier of the saved item.<br/>This identifier is a UUID.

type

String

The type of the saved item.<br/>The type indicates what can be stored in the data property.

Enum: SIMILARITY_SEARCH, VALUE_BASED_SEARCH, CROSS_ASSET_VALUE_BASED_SEARCH, DIGITAL_STEP_SEARCH, AREA_SEARCH, FINGERPRINT, LEGACY_FINGERPRINT, VIEW, TREND_HUB_2_VIEW, FILTER, CONTEXT_LOGBOOK_VIEW, FORMULA, AGGREGATION, DASHBOARD, MONITOR, MACHINE_LEARNING, PREDICTIVE, TOTALIZER, NOTEBOOK, PIPELINE,

name

String

The name of the saved item.

description

String

The description of the saved item.

data

Map of [object]

A Json Object representing the content of the saved item.<br/>This content is specific to the saved item type.<br/>The data is, by default, only available when retrieving a single saved item.<br/>This behaviour can be overridden in lists by explicitly providing &quot;includeData&quot; in the request URL.

extendedViewProperties

Map of [string]

Key value pairs representing the extended view properties of the saved item.<br/>This content is specific to the saved item type.

lastModifiedDate

Date

The UTC date when the saved item was last modified.

date-time

folder

Boolean

true if the saved item is a folder; false otherwise.

shared

Boolean

true if the saved item is shared; false otherwise.

owner

String

The name of the saved item's owner.

ownerUuid

String

The UUID of the saved item's owner.

ownerUserDetails

UserDetailsResource

parentId

String

The UUID of the folder where this saved item can be found.<br/>This folder is a saved item.

permissions

Set of [string]

A list of permissions on the saved item for the current logged in user.<br/>Possible permissions:<br/>* SAVED_ITEM_NO_PERMISSIONS - The item can not be accessed;<br/>* SAVED_ITEM_READ_ITEM - The item can be read;<br/>* SAVED_ITEM_WRITE_ITEM - The item can be updated.

_links

Map of Link

3.17. SavedItemTypeResource

Represents a SavedItemType definition

Field Name Required Type Description Format

name

String

description

String

category

String

_links

Map of Link

3.18. SessionModel

API model of a session

Field Name Required Type Description Format

data

X

Object

JSON object containing the definition of the preference

3.19. UserDetailsResource

Details about a user

Field Name Required Type Description Format

userId

String

Unique identifier

userName

String

Username

firstName

String

First name

lastName

String

Last name

3.20. UserInformationModel

Field Name Required Type Description Format

userUuid

String

The uuid of the owner of the new demo tag

Download PDF version | Download OpenAPI specifications