1. Overview

Spotfire Server REST API for Library items management.

1.1. Version information

Version : 2

1.2. Tags

  • library-upload : Spotfire Library Upload API

  • library-items : Spotfire Library API

2. Authentication and authorization

The API uses the OAuth 2.0 protocol for authentication and authorization, with the Spotfire Server itself as Authorization Server.

Note: The API does not use HTTP sessions so there is no need to maintain session cookies.

Note: All communication should always be done over HTTPS when using OAuth 2.0.

2.1. Basic steps

  1. Register an API client using the register-api-client command to obtain client credentials.

    When registering the client you specify what type of client it is, what grants and scopes the client should be able to use etc.

  2. Obtain an access token using one of the following alternatives

    • To use the Authorization Code grant follow the instructions in section 4.1 of RFC 6749.

    • To use the Client Credentials grant follow the instructions in section 4.4 of RFC 6749.

    • To use a Refresh Token follow the instructions in section 6 of RFC 6749.

      Additional information on how to get the access token

    • The OAuth 2.0 Authorization Server Metadata (RFC 8414) can be retrieved from: http[s]://<host>[:<port>]/spotfire/.well-known/oauth-authorization-server

    • The Authorization Endpoint can be accessed at: http[s]://<host>[:<port>]/spotfire/oauth2/auth

    • The Token Endpoint can be accessed at: http[s]://<host>[:<port>]/spotfire/oauth2/token

    • When calling the Token Endpoint the client must authenticate using the HTTP Basic authentication scheme as described in section 2.3.1 of RFC 6749, using the credentials obtained when registering the client (unless the client profile is native or user_agent, in which case no credentials are issued).

    • The initial request (to the Authorization Endpoint in the case of the Authorization Code grant, or to the Token Endpoint in the case of the Client Credentials grant) must include any and all scopes required to access the service(s) that the client intend to access (see the documentation of each service for details).

  3. Include the access token in all requests to the API, in an Authorization header as described in section 2.1 of RFC 6750.

    • The access token has a limited lifetime, after which a new token must be obtained by repeating step 2.

    • An access token is only valid for the services and operations described in the scope parameter provided when obtaining the access token. The available scopes are described in the documentation for each service.

2.2. Additional information

  • Four client profiles are supported: other, web, native and user_agent. The profile other should be used by a typically headless application performing requests on it’s own behalf. The profile web should be used by a server-side web application performing requests on behalf of an end-user. The profile native should be used by a native client, such as and iOS or Android app, performing requests on behalf of an end-user. The profile user_agent should be used by a client-side (JavaScript) web application, performing requests on behalf of an end-user.

  • The Authorization Code, Client Credentials and Refresh Token grants are supported.

  • Clients with profile web, native or user_agent can only use the Authorization Code and Refresh Token grants, clients with profile other can only use the Client Credentials grant.

  • Refresh tokens MAY be issued to allow access also when the end-user isn’t present (useful when for example performing periodic uploads or similar). To request a refresh token to be issued the scope offline should be included in the request to the Authorization Endpoint. For more information see section 1.5 of RFC 6749.

    • Refresh tokens that are no longer needed SHOULD be revoked, as described in RFC 7009.

  • Public clients (clients without client credentials) MUST use PKCE (RFC 7636). Confidential clients MAY use _PKCE.

  • Native clients may use any of the three ways of receiving the response listed in section 7 of RFC 8252.

    • To use Private-Use URI Scheme Redirection a custom URI scheme must be registered when registering the client.

    • To use Claimed "https" Scheme URI Redirection an authorized redirect URI must be registered when registering the client.

    • Loopback Interface Redirection is supported for all native clients. The scheme must be http. The host must be either 127.0.0.1 (IPv4) or [::1] (IPv6). The path may be either / or /auth. The port is variable.

  • Native clients SHOULD adhere to the guidelines outlined in OAuth 2.0 for Native Apps (RFC 8252).

  • All clients SHOULD implement support for OAuth 2.0 Authorization Server Issuer Identification (RFC 9207).

3. API Endpoint URLs

All API services can be accessed at the following location, where ServicePath is one of the entries in the Resources listing below:

http[s]://<host>[:<port>]/spotfire/api/rest/library/v2/<ServicePath>

Example:

https://example.com:8443/spotfire/api/rest/library/v2/upload/<jobId>

You can download the Open API Specification (OAS) for this REST API as a JSON file from the Spotfire Server at http[s]://<host>[:<port>]/spotfire/api/v2/api-docs?group=library-v2. This OAS file can be accessed at this location by all authenticated users (unless disabled through configuration). The OAS file can be used to generate client stubs, which will contain all types and methods that may be used with the API.

You can also browse the OAS for this REST API, using the Swagger UI, available at http[s]://<host>[:<port>]/spotfire/api/swagger-ui.html?urls.primaryName=library-v2

4. Usage

This API is used to upload & browse files of the Spotfire library. All calls assume that a successful authentication has been made, see above. The upload of a file is made through a number of calls.

Note
 Clients should be as resilient as possible, e.g. they should be able to handle any 4XX or 5XX http status codes and not just the ones documented here.
Note
 In later versions of this API, additional JSON properties might be added. Make the JSON response parsing done by the API client forgiving, so it can accept unexpected properties and different ordering.

5. Resources

5.1. Library-upload

5.1.1. Create upload job

POST /upload
Description

Starts a library upload job

Parameters
Type Name Description Schema Example

Body

Body
required

Information about the content to be uploaded

LibraryUploadJobRequest
Responses
HTTP Code Description Schema

201

Upload job created

LibraryUploadJob
Consumes

  • application/json

Produces

  • application/json

Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.library.write

5.1.2. Finish an upload

POST /upload/{jobId}/finish
Description

Finishes a started upload job

Parameters
Type Name Description Schema Example

Path

jobId
required

The job id

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Responses
HTTP Code Description Schema

200

The finished job

LibraryUploadJob
Produces

  • application/json

Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.library.write

5.1.3. Check the status of an upload job

GET /upload/{jobId}
Description

Can be used to see if the job succeeded or not, and what chunks have been successfully uploaded

Parameters
Type Name Description Schema Example

Path

jobId
required

The job id

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Responses
HTTP Code Description Schema

200

The status of the job

LibraryUploadJob
Produces

  • application/json

Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.library.write

5.1.4. Add data to an upload job

POST /upload/{jobId}
Description

Uploads data to an upload job

Parameters
Type Name Description Schema Example

Header

Content-MD5
optional

An MD5 digest, according to RFC 1864, of the uploaded data that can be used to verify data integrity.

string

Header

Digest
optional

A digest, according to RFC 3230 and RFC 5843, of the uploaded data that can be used to verify data integrity. Supported algorithms are MD5, SHA, SHA-256 and SHA-512.

string

Path

jobId
required

The job id

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Query

chunk
required

The chunk number

integer

Query

finish
optional

Indicates whether the upload should be immediately finished after this request

boolean
Responses
HTTP Code Description Schema

200

Content added to upload job

LibraryUploadJob
Produces

  • application/json

Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.library.write

5.1.5. Cancel an upload job

DELETE /upload/{jobId}
Description

Cancels an upload job

Parameters
Type Name Description Schema Example

Path

jobId
required

The job id

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Responses
HTTP Code Description Schema

200

The cancelled job

LibraryUploadJob
Produces

  • application/json

Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.library.write

5.2. Library-items

5.2.1. Get library item versions

GET /items/{itemId}/versions
Description

Returns all stored versions of a library item.

Parameters
Type Name Description Schema Example

Path

itemId
required

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Responses
HTTP Code Description Schema

200

The library item’s versions.

LibraryItemVersions

404

Library item not found.

ErrorResponse
Produces

  • application/json

Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.library.write

oauth2

spotfire-api-oauth2

api.library.read

5.2.2. Retrieves library item

GET /items/{itemId}
Description

Retrieves library item meta data.

Parameters
Type Name Description Schema Example

Path

itemId
required

The Library item unique ID.

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Query

attributes
optional

Optional: A comma separated list of item properties to fetch. Can be one or more of (all, path, permissions, properties, versions).

string
Responses
HTTP Code Description Schema

200

The library item’s meta data.

LibraryItem

404

Library item not found.

ErrorResponse
Produces

  • application/json

Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.library.write

oauth2

spotfire-api-oauth2

api.library.read

5.2.3. Update a library item

PATCH /items/{itemId}
Description

Update a library item

Parameters
Type Name Description Schema Example

Path

itemId
required

The library item ID.

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Query

conflictResolution
optional

The conflict resolution strategy to use, can be one of (KeepNew, KeepOld, KeepBoth). If no value is provided, then the default will be KeepBoth.

string

Body

Body
required

LibraryItem
Responses
HTTP Code Description Schema

200

The updated library item’s meta data

LibraryItem

404

Library item not found.

ErrorResponse
Consumes

  • application/json

Produces

  • application/json

Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.library.write

5.2.4. Delete library item

DELETE /items/{itemId}
Description

Deletes a library item.

Parameters
Type Name Description Schema Example

Path

itemId
required

The Library item ID.

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Responses
HTTP Code Description Schema

204

Delete successful.

404

Library item not found.

ErrorResponse
Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.library.write

5.2.5. Get library item version

GET /items/{itemId}/versions/{versionId}
Description

Returns a specified library item version.

Parameters
Type Name Description Schema Example

Path

itemId
required

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Path

versionId
required

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Responses
HTTP Code Description Schema

200

The library item version.

LibraryItemVersion

404

Library item not found.

ErrorResponse
Produces

  • application/json

Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.library.write

oauth2

spotfire-api-oauth2

api.library.read

5.2.6. Update library item version

PATCH /items/{itemId}/versions/{versionId}
Description

Updates a library item version.

Parameters
Type Name Description Schema Example

Path

itemId
required

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Path

versionId
required

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Body

Body
required

LibraryItemVersion
Responses
HTTP Code Description Schema

200

The updated version.

LibraryItemVersion

404

Library item not found.

ErrorResponse
Consumes

  • application/json

Produces

  • application/json

Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.library.write

5.2.7. Delete library item version

DELETE /items/{itemId}/versions/{versionId}
Description

Deletes a library item version.

Parameters
Type Name Description Schema Example

Path

itemId
required

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Path

versionId
required

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Responses
HTTP Code Description Schema

204

Delete successful.

404

Library item not found.

ErrorResponse
Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.library.write

5.2.8. Get information about the library

GET /info
Description

Get library’s root item, supported item types, limits and parameters

Responses
HTTP Code Description Schema

200

Information about the library.

LibraryInfo
Produces

  • application/json

Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.library.write

oauth2

spotfire-api-oauth2

api.library.read

5.2.9. Download library item content

GET /items/{itemId}/contents
Description

Downloads the content of a library item. Note that the downloaded file should be seen as an opaque object that may not be introspected or edited in any way, unless it’s in a publicly documented format (such as SBDF).

Parameters
Type Name Description Schema Example

Path

itemId
required

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Responses
HTTP Code Description Schema

200

The content of the library item

byte

404

Library item not found.

ErrorResponse
Produces

  • application/octet-stream

Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.library.write

oauth2

spotfire-api-oauth2

api.library.read

5.2.10. Get library folder items

GET /items/{itemId}/children
Description

Get library folder items' meta data.

Parameters
Type Name Description Schema Example

Path

itemId
required

The library folder ID.

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Query

attributes
optional

A comma separated list of optional item properties to fetch. Can be one or more of (all, path, permissions, properties, versions)

string
Responses
HTTP Code Description Schema

200

The library folder items' meta data.

LibraryItem

404

Folder not found.

ErrorResponse
Produces

  • application/json

Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.library.write

oauth2

spotfire-api-oauth2

api.library.read

5.2.11. Query library items

GET /items
Description

Returns all items, up to the provided limit, in the given location that matches the given search expression. Only items that the calling user has access to will be returned. The parameters searchExpression, locationId and maxResults can be used together. Otherwise, the parameters path and type can be used together. The parameter attributes can be used with both parameter combinations described above.

Parameters
Type Name Description Schema Example

Query

attributes
optional

A comma separated list of optional item properties to fetch. Can be one or more of (all, path, permissions, properties, versions). Can be combined with all other parameters.

string

Query

locationId
optional

Unique ID of a folder (and all sub-folders) in which to search, or null if the entire library should be searched. Can be combined with searchExpression and maxResults parameters.

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Query

maxResults
optional

The maximum number of items to be returned or a number less than or equal to 0 if all matching items should be returned. If no value is set then the server will set a default maximum number of results.Can be combined with searchExpression and locationId parameters.

integer

Query

path
optional

The location of the item, a path starts with a slash and each component is separated with a slash as well, may not be empty or null. Can be combined with type parameter.

string

Query

searchExpression
optional

Library search expression. Can be combined with locationId and maxResults parameters.

string

Query

type
optional

The type of the item. Can be combined with path parameter.

string
Responses
HTTP Code Description Schema

200

List of items in the given location which match the search expression

LibraryItems

404

No matching items found or user has no access to read them.

ErrorResponse
Produces

  • application/json

Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.library.write

oauth2

spotfire-api-oauth2

api.library.read

5.2.12. Create a new library item

POST /items
Description

Create a new library item. Can be a new folder, or a copy of an existing library item

Parameters
Type Name Description Schema Example

Query

conflictResolution
optional

The conflict resolution strategy to use, can be one of (KeepNew, KeepOld, KeepBoth). This is only used when copying an item. If no value is provided, then the default will be KeepBoth.

string

Query

copyOf
optional

The id of a library item to clone

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Query

copyOfVersion
optional

The id of a library item version to clone

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Body

Body
required

The folder to create (type, title, description and parentId). To copy an item only parentId is needed/utilized.

LibraryItemNew
Responses
HTTP Code Description Schema

201

The newly created library folder

LibraryItem

401

The user is not authorized to create folder

ErrorResponse

404

Parent folder not found

ErrorResponse
Consumes

  • application/json

Produces

  • application/json

Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.library.write

6. Definitions

6.1. UploadInfo

Library info data including root library item and library item types.

Name Description Schema

allowedItemTypes
optional

Item types allowed to be uploaded

<string> array

maxConcurrentJobsPerClient
optional

The maximum number of concurrent jobs per client

integer

maxUploadSizeBytes
optional

The maximum uploadable item size

integer

6.2. LibraryItem

An item in the library.

Name Description Schema

id
optional

Unique ID of the item.
Example : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

string

title
optional

Title of the item.
Example : "Library Item Title"

string

path
optional

Path of the item
Example : "/My Folder/My Item"

string

description
optional

Description of the item, or null if there is no description.

string

type
optional

Type of the item.

string

createdBy
optional

The user that created the item, or null if not known.

UserPrincipal

created
optional

The date and time when the item was created.

string

modifiedBy
optional

The user that last modified the item, or null if not known.

UserPrincipal

modified
optional

The date and time when the item was last modified.

string

accessed
optional

The date and time when the item was last accessed.

string

parentId
optional

Unique ID of the parent item.

string

size
optional

The size of the item in bytes.
Example : "1234"

integer

properties
optional

Properties set on the item.

<LibraryProperty> array

permissions
optional

Permissions for the item.

<AclEntry> array

versionId
optional

Represents the unique ID of a library item versions.

string

itemVersions
optional

The list of library item versions.

<LibraryItemVersion> array

isFavorite
optional

True if the item is set as favorite by the current user.

boolean

favoriteCount
optional

how many times this item has been set as favorite

integer

6.3. LibraryItemVersions

A collection of library item versions.

Name Description Schema

itemVersions
optional

The collection of library item versions.

<LibraryItemVersion> array

6.4. LibraryInfo

Library info data including root library item and library item types.

Name Description Schema

rootItem
optional

The ID of the library root item.

string

itemTypes
optional

Defined library types.

<string> array

uploadInfo
optional

Information about library uploads

UploadInfo

downloadInfo
optional

Information about library downloads

DownloadInfo

6.5. LibraryItemVersion

Library item version details.

Name Description Schema

id
optional

ID of the version.
Example : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

string

created
optional

The date and time when the item was created.

string

createdBy
optional

The user that created the version, or null if not known.

UserPrincipal

formatVersion
optional

The format version, if any, of the content of the version.

string

size
optional

The size of the content of the version in bytes.

integer

name
optional

The name of the version, if any.

string

comment
optional

Comment on the version, if any.

string

restoredFromVersionId
optional

The ID of the version from which this version was restored from, or null if this version was not created by restoring from another version.

string

restoredFromTimestamp
optional

The date and time when the version from which this version was restored was created, or null.

string

6.6. AclEntry

Represents an Access Control List entry for an item in the Library. Many ACL entries may be associated with a library item , each representing the permissions set for one user or group.

Name Description Schema

principalId
optional

Unique id of the principal for which the permissions are set.

string

principalName
optional

The name of the principal for which the permissions are set.

string

domainName
optional

The domain name of the principal for which the permissions are set.

string

principalType
optional

The type of the principal (user or group).

PrincipalType

permissions
optional

The list of permissions.

<LibraryPermission> array

inheritedFromId
optional

The id of the folder from which the permissions have been inherited. Absence of a value indicates that the permissions are set on the requested item itself.

string

6.7. Error

Name Description Schema

code
optional

string

description
optional

string

6.8. LibraryItems

A collection of library items.

Name Description Schema

items
optional

The list of library items.

<LibraryItem> array

6.9. LibraryProperty

A property of an item in the Library.

Name Description Schema

key
optional

Property key.

string

values
optional

Property Value.

<string> array

versioned
optional

Indicates if property is versioned or not.

boolean

6.10. UserPrincipal

A user principal in the User Directory.

Name Description Schema

id
optional

ID of the principal.
Example : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

string

name
optional

The name of the principal.

string

domainName
optional

The domain name of the principal. If no domain has been set, then the name of the internal SPOTFIRE domain is returned.

string

displayName
optional

The display name of the principal.

string

6.11. ErrorResponse

Name Description Schema

error
optional

Error

6.12. LibraryUploadJob

A library upload job.

Name Description Schema

numberOfChunks
optional

The number of chunks in which the data will be uploaded, if known.

integer

numberOfBytes
optional

The size of the data that will be uploaded, if known.

integer

jobId
optional

ID of the upload job.

string

item
optional

The library item uploaded.

LibraryItem

uploadedChunks
optional

A list of the chunks already uploaded.

<integer> array

finishedAt
optional

The time at which the upload job was finished.

string

cancelledAt
optional

The time at which the upload job was cancelled.

string

6.13. DownloadInfo

Information about downloads in the public Library REST API

Name Description Schema

allowedItemTypes
optional

Item types allowed to be downloaded

<string> array

6.14. LibraryItemNew

Represents a new folder or a copied item. For copied items, only parent ID is used.

Name Description Schema

title
optional

Title of the item. Required if creating a new folder.
Example : "Library Item Title"

string

description
optional

Description of the item, or null if no description has been set.

string

type
optional

Type of the item. Required if creating a new folder.

string

parentId
optional

The ID of the parent item. Required if creating a new folder or cloning an item.

string

6.15. LibraryItemUpload

Library item details.

Name Description Schema

title
optional

Title of the item.
Example : "Library Item Title"

string

description
optional

Description of the item, or null if there is no description.

string

type
optional

Type of the item.

string

parentId
optional

Unique ID of the parent item.

string

6.16. LibraryUploadJobRequest

A library upload job request.

Name Description Schema

numberOfChunks
optional

The number of chunks in which the data will be uploaded, if known.

integer

numberOfBytes
optional

The size of the data that will be uploaded, if known.

integer

item
optional

Information about the library item to upload.

LibraryItemUpload

overwriteIfExists
optional

Indicates whether or not the item should be overwritten if it already exists.

boolean

6.17. PrincipalType

Represents principal type (user or group).

Enum value Schema

user

string

group

string

6.18. LibraryPermission

Represents a permission on an item in the Library. Note that all permissions are independent of each other and that users that are granted WRITE access in most cases also should have READ and EXECUTE access. Possible values are: Read, Write, Owner & Execute.

Enum value Schema

Read

string

Write

string

Owner

string

Execute

string

7. Security

7.1. spotfire-api-oauth2

Type : oauth2
Flow : application
Token URL : /spotfire/oauth2/token

Name Description

api.library.read

Reading from the library

api.library.write

Writing to the library

8. Common Responses

HTTP Code Description Reason

401

Not Authenticated

The client has not been authenticated

403

Not Authorized

The client is not authorized to access the requested resource

500

Internal Server Error

Something went wrong when the processing the request

9. Error Codes

A request to the API that results in an ErrorResponse will have a response body with the following format:

{
  "error": {
    "code": "server_busy",
    "description": "The server is currently too busy to handle the request"
  }
}

where description is a description of the error, and code can be one of the following predefined API error codes:

Error Code HTTP Status Description

invalid_request

400

The request was invalid or incomplete

precondition_failed

400

A precondition for the request was not met

bad_digest

400

The supplied digest is not valid or does not match the digest of the request body

not_authenticated

401

The API client is not authenticated

not_authorized

403

The API client is not authorized to access the requested resource

not_found

404

The requested resource cannot be found

job_unknown

404

The referenced job does not exist, or the client does not have access to it

method_not_allowed

405

The HTTP method is not allowed

already_exists

409

The resource already exists

limit_exceeded

413

A resource limit has been reached

unsupported_mediatype

415

The media type of the request payload is unsupported

rate_limit_exceeded

429

A resource limit has been reached

internal_error

500

The server encountered an error when processing the request

server_busy

503

The server is currently too busy to handle the request

10. Configuration

The API is enabled by default. To disable it or to make other configuration changes, use the config-web-service-api command. For more information see the section Configuration using the command line of the Spotfire© Server and Environment Installation and Administration manual.

11. Additional resources

For more information please refer to these resources: