> For the complete documentation index, see [llms.txt](https://docs.tivity.one/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tivity.one/extensibility-and-integration/rest-api.md).

# REST API

The TIVITY API supports processing of instances and documents outside the platform. List ID can be a class ID or query ID. REST API

**Base URL (placeholder)**\
Use the following placeholder in all examples:

`https://{host}/api/v1`

***

### Instances

#### Summary

| Method name | HTTP method | URL                                                     |
| ----------- | ----------- | ------------------------------------------------------- |
| Create      | POST        | `/instance/{workspaceId}/{appId}/{listId}`              |
| ReadAll     | GET         | `/instance/{workspaceId}/{appId}/{listId}`              |
| ReadOne     | GET         | `/instance/{workspaceId}/{appId}/{listId}/{instanceId}` |
| Update      | PUT         | `/instance/{workspaceId}/{appId}/{listId}/{instanceId}` |
| Delete      | POST        | `/instance/{workspaceId}/{appId}/{listId}/{instanceId}` |

***

#### Create

**POST** `https://{host}/api/v1/instance/{workspaceId}/{appId}/{listId}` REST API

Creates a new instance in the specified list.

**Headers**

* **Authorization**: Bearer token REST API

**Request Body (example)** REST API

```
{
  "instance": {
    "fields": {
      "{FieldKey1}": "{FieldValue1}",
      "{FieldKey2}": "{FieldValue2}",
      "{FieldKey3}": "{FieldValue3}"
    }
  }
}
```

***

#### ReadAll

**GET** `https://{host}/api/v1/instance/{workspaceId}/{appId}/{listId}` REST API

Reads all instances of the specified list.

**Headers**

* **Authorization**: Bearer token REST API

**Response (example)** REST API

```
{
  "cursor": 1,
  "lastPage": false,
  "pageInfo": "PD94bWwgdmVyc2...RGF0YT4=",
  "instances": [
    {
      "id": "/instance/{workspaceId}/{appId}/{listId}/{instanceId}",
      "fields": {
        "{FieldKey1}": "{FieldValue1}"
      }
    }
  ]
}
```

***

#### ReadOne

**GET** `https://{host}/api/v1/instance/{workspaceId}/{appId}/{listId}/{instanceId}` REST API

Reads one instance of the specified list.

**Headers**

* **Authorization**: Bearer token REST API

**Response (example)**

```
{
  "instance": {
    "id": "/instance/{workspaceId}/{appId}/{listId}/{instanceId}",
    "fields": {
      "{FieldKey1}": "{FieldValue1}",
      "{FieldKey2}": "{FieldValue2}",
      "{FieldKey3}": "{FieldValue3}"
    }
  }
}
```

***

#### Update

**PUT** `https://{host}/api/v1/instance/{workspaceId}/{appId}/{listId}/{instanceId}`

Updates an existing instance of the specified list.

**Headers**

* **Authorization**: Bearer token

**Response (example)**

Comma-separated fields list, returns all if left empty.

```
{
  "instance": {
    "id": "/instance/{workspaceId}/{appId}/{listId}/{instanceId}",
    "fields": {
      "{FieldKey1}": "{FieldValue1}",
      "{FieldKey2}": "{FieldValue2}",
      "{FieldKey3}": "{FieldValue3}"
    }
  }
}
```

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"
          } 
      } 
   } 
}
```

***

#### Delete

**POST** `https://{host}/api/v1/instance/{workspaceId}/{appId}/{listId}/{instanceId}`

Deletes an existing instance of the specified list. REST API

***

### Documents

#### Download

**GET** `https://{host}/api/v1/document/{workspaceId}/{appId}/{listId}/{instanceId}` REST API

Downloads a document of an instance. REST API

**Headers**

* **Authorization**: Bearer token REST API

**Request Body (example)** REST API

```
{
  "type": "Preview"
}
```

Possible values for `type`: `Document`, `Thumbnail`, `Preview`. REST API

***

#### Upload

**POST** `https://{host}/api/v1/document` REST API

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

**Headers**

* **Authorization**: Bearer token REST API

**Request Body**

* File as a byte stream. REST API

**Response (example)** REST API

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

***

## Workflow Execution

The API supports executing workflows on a **class/list** or on a specific **instance**. Workflows can be started and continued by passing back the `state` from an `Input` response.

> Note: the OpenAPI specification uses `{teamId}` in the path, but this documentation refers to the same identifier as **Workspace ID**. Workflow-OpenAPI

***

### Endpoints

#### Execute Class Workflow

**POST** `https://{host}/api/v1/instance/{workspaceId}/{appId}/{listId}/workflow/{workflowId}` Workflow-OpenAPI

Executes a class workflow of the specified list. Workflow-OpenAPI

***

#### Execute Instance Workflow

**POST** `https://{host}/api/v1/instance/{workspaceId}/{appId}/{listId}/{instanceId}/workflow/{workflowId}` Workflow-OpenAPI

Executes an instance workflow for the specified instance. Workflow-OpenAPI

***

### Request Body

The request body is a **WorkflowRequest**. Workflow-OpenAPI

**state** *(optional)*\
Only set when continuing a workflow execution. The value must be taken from the `state` returned in a previous `Input` response. Workflow-OpenAPI

**parameters** *(optional)*\
Parameters to be sent to the workflow execution. Parameters may be sent without the execution explicitly requesting them. Workflow-OpenAPI

#### Example (start a workflow)

```
{
  "parameters": {
    "StartParameter": "This is a test"
  }
}
```

#### Example (continue a workflow)

```
{
  "state": "{state-from-previous-input-response}",
  "parameters": {
    "Parameter1": "Value1"
  }
}
```

***

### Response Body

The response body is a **WorkflowResponse**. Workflow-OpenAPI

**kind** *(required)*\
One of: `Value`, `Input`, `Error`. Workflow-OpenAPI

**state** *(only when kind = Input)*\
The state that must be passed into the next request to continue the workflow. Workflow-OpenAPI

**value** *(only when kind = Value)*\
The success result of the workflow execution. Workflow-OpenAPI

**input.parameters** *(only when kind = Input)*\
List of requested parameters (each contains a `key`). Workflow-OpenAPI

**error** *(only when kind = Error)*\
Failure result as a string. Workflow-OpenAPI

***

### Workflow Response Examples

#### Value (success)

```
{
  "kind": "Value",
  "value": {
    "result": "OK"
  }
}
```

value contains the return value of a value and can be any of the [supported types](#supported-parameter-and-value-types):

```
{
  "kind": "Value",
  "value": 1234
}
```

***

#### Input (pending – more parameters required)

```
{
  "kind": "Input",
  "state": "{state-to-continue}",
  "input": {
    "parameters": [
      { "key": "DocumentParameter" }
    ]
  }
}
```

***

#### Error (failure)

```
{
  "kind": "Error",
  "error": "Errors occurred when mapping workflow parameter values."
}
```

***

### Supported Parameter and Value Types

Workflow parameters and values support the following types:

**Boolean, Byte, DateTime, Double, Document, Float, Guid, Integer, List, Long, Object, Numeric, Short, String, Table.**

***

### Status Codes and Validation Rules

* **400** – Returned when request parameters are invalid.
* **401** – Returned when the workspace, app, class/list, instance, or workflow cannot be accessed.
* **404** – Returned when the workspace, app, class/list, instance, or workflow cannot be found.

Additional workflow execution rules:

* When the workflow requests additional parameters, an **Input** response is returned.
* When workflow parameters are unsupported or invalid, an **Error** response is returned.
* When an unsupported value is returned by the workflow, an **Error** response is returned.
* When any execution error occurs during workflow processing, an **Error** response is returned.