REST API

The TIVITY API supports processing of instances and documents outside the platform.

Summary

method name	HTTP method	URL
Create	POST	v1/instance/:teamId/:appId/:listId
ReadAll	GET	v1/instance/:teamId/:appId/:listId
ReadOne	GET	v1/instance/:teamId/:appId/:listId/:instanceId
Update	PUT	v1/instance/:teamId/:appId/:listId/:instanceId
Delete	POST	v1/instance/:teamId/:appId/:listId/:instanceId
Download	GET	v1/document/:teamId/:appId/:listId/:instanceId
Upload	POST	v1/document

List ID can be a class ID or query ID.

Instance / Create

POST https://dev.tivity.one/api/instance/:teamId/:appId/:listId

Creates a new instance in the specified list. Returns class ID if list ID is from a query while requesting.

Path Parameters

Name	Type	Description
teamId	string	ID of the team where the instances are from.
appId	string	ID of the app where the instances are from.
listId	string	ID of the class or query.

Headers

Name	Type	Description
Authorization	string	Bearer token, grants access to the API.

Request Body

Name	Type	Description
json object	string	{ “instance”: { “fields”: { "FieldKey1": “FieldValue1”, "FieldKey2": “FieldValue2”, "FieldKey3": “FieldValue3” } } }

200 Return an instance object with the created field list and the ID. This ID could be used to arrange the 'Read' URL.

{
    "instance": {
     "id": "/instance/{teamId}/{appId}/{listId}/{instanceId}",
     "fields": {
       "{FieldKey1}": “{FieldValue1}”,
       "{FieldKey2}": “{FieldValue2}”,
       "{FieldKey3}": “{FieldValue3}”,
       }
    }
}

Instance / ReadAll

GET https://dev.tivity.one/api/v1/instance/:teamId/:appId/:listId

Reads all instances of the specified list.

Path Parameters

Name	Type	Description
teamId	string	ID of the team where the instances are from
appId	string	ID of the app where the instances are from
listId	string	ID of the class or query

Headers

Name	Type	Description
Authentication	string	Bearer token, grants access to the API.

Request Body

Name	Type	Description
json object	string	pageBy: (page(n+1)):(take(n)) - page: page number - take: next limit number of entries pageInfo: Not needed for the 1st page. The pageInfo is obtained in the response. select: list of property names to display in the response, display all if left empty. filter: possible values - logical operators: AND | OR - operators: EQ (equal) | NEQ (not equal) | IN (contains) - property: enclosed with { and }. Exmpl -> {propName} - value: enclosed with ' '. Exmpl -> 'value' - group with parenthesis: (term) - filter term starts and ends always with ( and ) filter example: ({Description} NEQ 'Value' AND ({Name} EQ 'Value2' OR {Name} IN 'Value3') AND {KeyX} NEQ 'Value4') sortBy: property:[Asc | Desc] example JSON body { "pageBy": "0:10", "select": [ "Name", "Description" ], "filter": "(({Name} IN '4' AND {Description} IN 'common') OR {Name} IN '5')", "sortBy": "Descriptoin:ASC" }

200 Instances successfully retrieved. The pageInfo must be added to the next request.

{
  "cursor": 1,
  "lastPage": false,
  "pageInfo": "PD94bWwgdmVyc2…………9mU2VyaWFsaXplRGF0YT4=",
  "instances": [
    	{ 
	       "id": "/instance/{teamId}/{appId}/{listId}/{instanceId}",
    		"fields": {
     			"{FieldKey1}": “{FieldValue1}”,
	…….
	]
}

404 Could not find the list with the given ID.

{    "message": "Cannot find instances."}

Instance / ReadOne

GET https://dev.tivity.one/api/v1/instance/:teamId/:appId/:listId/:instanceId

Reads one instance of the specified list.

Path Parameters

Name	Type	Description
teamId	string	ID of the team where the instances are from.
appId	string	ID of the app where the instances are from.
listId	string	ID of the class or query.
instanceId	string	ID of the instance.

Headers

Name	Type	Description
Authentication	string	Bearer token, grants access to the API.

200 Instance successfully retrieved.

{
  "instance": {
    "id": "/instance/{teamId}/{appId}/{listId}/{instanceId}",
    "fields": {
     "{FieldKey1}": “{FieldValue1}”,
     "{FieldKey2}": “{FieldValue2}”,
     "{FieldKey3}": “{FieldValue3}”,
    }
  }
}

404 Could not find the instance with the given ID.

{    "message": "Cannot find instance."}

Instance / Update

PUT https://dev.tivity.one/api/vi/instance/:teamId/:appId/:listId/:instanceId

Updates an existing instance of the specified list.

Path Parameters

Name	Type	Description
teamId	string	ID of the team where the instances are from.
appId	string	ID of the app where the instances are from.
listId	string	ID of the class or query.
instanceId	string	ID of the instance.

Headers

Name	Type	Description
Authentication	string	Bearer token, grants access to the API.

Request Body

Name	Type	Description
json object	string	Comma-separated fields list, returns all if left empty. { "instance": { "fields": { "{FieldKey1}": “{FieldValue1}”, "{FieldKey2}": “{FieldValue2}”, "{FieldKey3}": “{FieldValue3}” } } }
json object (docs)	string	Optionally documents from the DocumentStore (see Upload call) can be inserted. But this works only for document classes with the 'Upload' action. { "instance": { "fields": { "{FieldKey1}": “{FieldValue1}”, "{FieldKey2}": “{FieldValue2}”, "{FieldKey3}": “{FieldValue3}”, "File": { "Id": "8172f7aa...", "Name": "test-123-9.pdf", "MimeType": "application/pdf" } } } }

200 Instance successfully updated.

{
  "instance": {
    "id": "/instance/{teamId}/{appId}/{listId}/{instanceId}",
    "fields": {
     "{FieldKey1}": “{FieldValue1}”,
     "{FieldKey2}": “{FieldValue2}”,
     "{FieldKey3}": “{FieldValue3}”,
    }
  }
}

404 Could not find the instance with the given ID.

{    "message": "Cannot find instance."}

Instance / Delete

DELETE http://dev.tivity.one/api/v1/instance/:teamId/appId/:listId/:instanceId

Deletes an existing instance of the specified list.

Path Parameters

Name	Type	Description
teamId	string	ID of the team where the instances are from.
appId	string	ID of the app where the instances are from.
listId	string	ID of the class or query.
instanceId	string	ID of the instance.

Headers

Name	Type	Description
Authorization	string	Bearer token, grants access to the API.

200 no body returned for response.

404 Could not find the instance with the given ID.

{    "message": "Cannot find instance."}

Document / Download

GET http://dev.tivity.one/api/v1/document/:teamId/appId/:listId/:instanceId

Downloads a document of an instance.

Path Parameters

Name	Type	Description
teamId	string	ID of the team where the instances are from.
appId	string	ID of the app where the instances are from.
listId	string	ID of the class or query.
instanceId	string	ID of the instance.

Headers

Name	Type	Description
Authorization	string	Bearer token.

Request Body

Name	Type	Description
json object	string	Type: Type of the document to download. - Possible values: [ Document | Thumbnail | Preview ] { "type": "Preview" }

200 Byte stream as response.

Document / Upload

POST http://dev.tivity.one/api/v1/document

Uploads a temporary document for later use. The returned document ID can be used for document files.

Headers

Name	Type	Description
Authorization	string	Bearer token, grants access to the API.

Request Body

Name	Type	Description
Document Content	object	File as a byte stream.

200 Returns a document ID for later use.

{
  "documentId": "c626d133-047c-494a-a0d7-775b1b40db7a"
}