Overview | Develop your own integration on the Wrike API

DH Public API Overview

Model Overview

Datahub introduces several interconnected entities

Database
Record
Field
Folder (not to be mistaken with Folder in Wrike)

Database contains Records (rows) and defines their structure via Fields

Records are elements of customer data

Each Record in a Database has the same set of Fields. Each field has its data type along with some type-specific settings

Databases belong to Wrike Spaces and are organized through Folders

Each Wrike Space always have exactly one root Folder

Folders can contain other Folders (which allows to have a complex navigation tree) and Databases

Endpoints/Operations Overview

Navigating folders

All the information within Datahub belongs to spaces and is organized into folders. Each space has exactly one root folder. Each folder (including the root folder) may contain other folders and databases

to get the root folder of a space, use
```
GET /spaces/{spaceId}/root/folder
```

if a folder ID (or IDs) is already known, use

GET /folders?folderIds={ids}

GET /folders/{folderId}

folders form a navigation tree, so you can query subfolders of a known folder
```
GET /folders/{folderId}/folders
```
It is also possible to query the entity tree using the withDescendants parameter
```
GET /folders?folderIds={ids}&withDescendatnts=true
```

Retrieving Databases

Databases always reside in folders, so to get a database, we need either its ID or the ID of a containing folder

```
GET /folders/{folderId}/databases
```
```
GET /databases?databaseIds={ids}
```
```
GET /databases/{databaseId}
```

Retrieving Database Structure (Fields)

Databases define the structure (model) of stored records via fields. It is possible to query fields individually (by ID) or in batches

```
GET /databases/{databaseId}/fields
```

GET /databases/{databaseId}/fields/{fieldId}

Retrieving Records

Records can be retrieved individually (by ID) or in batches

```
GET /databases/{databaseId}/records
```

GET /databases/{databaseId}/records/{recordId}

Records can be filtered by fields value. Available operators by field type:

Single value type

All types

isNull
isNotNull
equals
notEquals
isOneOf
isNoneOf

String types

stringContains
stringNotContains
stringStartsWith
stringEndsWith

Number and Date types

between
greaterThan
greaterThanOrEqualTo
lessThan
lessThanOrEqualTo

Array value type

isEmpty
isNotEmpty
containsAll
containsOnly
intersects
notIntersects

Creating Entities

To create an entity, issue a POST request to the following endpoints

```
/folders
```
```
/databases
```
```
/databases/{databaseId}/fields
```
```
/databases/{databaseId}/records
```
- note that this endpoint allows creating multiple records at once

Editing or Deleting Entities

To edit or delete an entity, issue a PATCH or DELETErequest to the following endpoints

```
/folders/{folderId}
```
```
/databases/{databaseId}
```

/databases/{databaseId}/fields/{fieldId}

```
/databases/{databaseId}/records/{recordIds}
```
- note that this endpoint allows deleting multiple records at once

Batch Editing of Records

It is possible to mass-edit multiple records with a single request

```
PATCH /databases/{databaseId}/records
```

Pagination Mechanism

Some endpoints may return a large number of entities. To avoid sending too much data at once, we employ a pagination mechanism in:

```
GET /databases/{databaseId}/records
```
```
GET /databases/{databaseId}/fields
```
```
GET /folders/{folderId}/databases
```
```
GET /databases
```
```
GET /folders
```
```
GET /folders/{folderId}/folders
```

Any of these endpoints has an optional pagination parameter which contains

nextPageToken - obtained from the previous page response
limit - how many entities to return in a single page (default=100, max=1000)

The first page is obtained without specifying a page token. Response will contain a token for querying the next page if there is more data which can fit on the page.

Note that page tokens are session-bound so it is impossible to use them after a session expires. Currently the session lasts for up to 3 hours.

Formula Handling

The API does not validate non-existent field IDs, resulting in status code 200. Such fields will be represented with placeholders in the field editor in UI and ignored in calculations.
The API does not validate field operations. For instance, multiplying DATE by DATE cannot yield meaningful calculation. Users who are creating formulas in API should understand the field combinations. Such broken formulas will be shown with a validation error in UI in the field editor.
Only fields from the current database can be used. To use fields from another database, you must create a mirror of that field in the current database.
Formulas and their output types are not validated for mismatched operations. Wrike selects the actual output format based on the operands.
Use the $today variable to represent the today() function.

Idempotency mechanism

It is possible that the API client is unable to tell apart situations where an edit request was not received and processed by the server from situations where a request was processed and the response was lost. For example, this may happen due to network problems. So in the case of duplicated requests from the client, the effect on the system should be the same as the effect of of a single request (this behavior is called idempotent).

The current API guarantees idempotency of PATCH and DELETE requests (as required according to REST practices). Additionally, POST requests are designed in a way to support idempotency. That is why the request body for all POST requests has to contain a requestId field. The client has to generate a unique requestId for each request. In the case of a retry, the client should use the same requestId as was sent with the request that is being retried. You can use any non-empty value for the requestId field, good practice is to use a freshly generated UUID.

Note that for POST endpoints idempotent retry is supported within a short period of time after the initial request (3 hours). This time period is an implementation detail and is subject to change without notice.