# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tivity.one/extensibility-and-integration/rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.