Back to top

Labfolder ELN API v2 Beta

Latest

Pre-Release Notice

This API is still under active development. This means endpoint semantics and formats might change as we finalize the implementation. There may still be some bugs as well, but we believe getting it into the hands of our users sooner will help the process move faster.

Optional fields might be added to requests and additional fields might be added to responses without notice. To ensure the smoothest possible transition please make sure your code does not rely on the exact object structure returned and ignores unknown properties.

As a general guideline for error handling, more emphasis should be paid to the status codes rather than the error messages.

“null” values

We’re aware of an issue with the library that we use to generate the API documentation in which nullable string properties are represented with the value "null" in the documentation. The API will never return “null” (as a string), only either a valid id (in string form “12345”) or null.

As an example, see the properties group_id and folder_id under the List Projects resource

Identity Access Management (IAM)

Labfolder has a feature IAM, in which we delegate our application security to the Labforward Identity & Access Management (IAM) application.

This feature will be enabled for cloud users for the time being. Once enabled, all users should log into Labfolder using a browser where they will be prompted to reset their passwords. Following the password reset, users can use the POST /auth/login endpoint as before to login and retrieve their authentication tokens.

Please be notified that -

  • Tokens will be JWT tokens with a slightly shorter expiry date, but they will serve the same purpose and have the same use as before.

  • There is no support for HTTP-Basic API calls. Only use the Authorization header method.

Version

This is API v2 build #

efd9c49c680b30091b2be795217c5a5e1d70e2a6

Changelog

2023-10-04

Changed

  • Removed the Token prefix from the Authorization header in favor of Bearer

Added

  • When project collaboration is enabled, we can provide the editors of the specified entry.

2023-06-14

Added

  • Added a new endpoint to list all available Incident Reports

  • Added a new endpoint to download Incident Report data

2023-05-03

Added

  • Added a new (and preferred) format for authentication via Authorization header - Authorization: Bearer xxxxx

Access

Location

The API can only be accessed via HTTPS.

You can reach the API for the cloud instance at

https://labfolder.labforward.app/api/v2/

Local installations can access the API using the respective domain with the path /api/v2/ appended.

So if your server is reachable at https://labfolder.mycompany.lan the API endpoint is located at

# Note: `/api/v2/` is appended to the standalone server url

https://labfolder.mycompany.lan/api/v2/

Authentication

A token is required to perform API requests. You may retrieve a token from the login endpoint. Once acquired the token should either be provided:

  1. in the Authorization header, or
  2. in the username field for HTTP-Basic authentication

Note that option 1 should always work, whereas option 2 is unavailable while the server has the Identity Access Management feature (IAM) enabled.

*Important!* Your API token should never be shared or made publicly accessible. No one from our company will ever ask you for this value, or your login credentials.

Option 1: using the Authorization Header

curl -H "Authorization: Bearer $LABFOLDER_API_TOKEN" <API_RESOURCE_PATH_GOES_HERE>

Option 2: using HTTP-Basic Authentication (unavailable when the IAM Feature is enabled)

# Note the proceeding ':'
curl -u "$LABFOLDER_API_TOKEN:" <API_RESOURCE_PATH_GOES_HERE>

Endpoints

Login - Generate Token
POST/auth/login

Generate a token which can be used to make API requests.

Example URI

POST /api/v2/auth/login
Request  Generate Token
HideShow
Headers
Content-Type: application/json
Body
{
  "user": "luke.skywalker@starwars.com",
  "password": "password"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "user": {
      "type": "string",
      "description": "email of the user"
    },
    "password": {
      "type": "string",
      "description": "password of the user"
    }
  },
  "required": [
    "user",
    "password"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "token": "MTZmNTigNWMtNWJ34y00NDgwL12wM2ItZTM4NzFGYzU1NTJm",
  "expires": "2017-09-04T13:27:55.641+0200"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "generated token"
    },
    "expires": {
      "type": "string",
      "description": "expiration date of the token"
    }
  },
  "required": [
    "token",
    "expires"
  ]
}

Logout - Invalidate Tokens
POST/auth/logout

Invalidate all API access tokens.

Example URI

POST /api/v2/auth/logout
Response  204

Concepts

User Agent Required

All requests MUST include a User-Agent header. Please include the name of your application and your e-mail address so we can contact you if needed.

User-Agent: My Application; email@domain.tld

if you do not provide a User-Agent we will return a 400 Bad Request.

Parameters & Body Format

Some GET requests can take optional parameters which are included in the query string and must be UTF-8 encoded.

# Example query string usage

?offset=0&limit=20&sort=-title

The body format of POST, PATCH, PUT, and DELETE request is JSON and the corresponding Content-Type header must be set to application/json.

# Set Content-Type header and provide JSON body

> curl -u "${LABFOLDER_API_TOKEN}:" -H "Content-Type: application/json" -X POST -d {...JSON...} <API_RESOURCE_PATH_GOES_HERE>

File upload formats

For an upload of a file you can send pure arbitrary byte data in the request.
However, you may also choose to upload a file using Base64 encoding. To do so, it is required to add the header Content-Transfer-Encoding : base64, and the body should contain contents of the file as Base64 string.

Compression

All requests including Accept-Encoding: gzip header wil get compressed content as response.

Accept-Encoding: gzip

if you do not provide Accept-Encoding we will return uncompressed content.

Skipping Response Body

When creating or updating a resource the API can be configured to not return the resulting object in the message body. This can be accomplished by providing a custom header with the request:

`X-LF-SKIP-BODY: true`

No message body will be provided in the response and the HTTP response code will be 204. This may be useful in situations where minimizing bandwidth is a concern and when the resulting resource size is large (for example: table elements or text elements).

Note: if the header is not provided or when a value other than true is given it will be ignored and the API will default to returning the full message body.

Pagination

Some requests return paginated results of items (usually 20 at a time). Paginated items will be returned as a JSON array:

[
    {...some JSON...},
    {...some JSON...},
    {...some JSON...},
    {...some JSON...}
]

The total amount of found items will be available in a header X-Total-Count. This header will always be present for pageable requests.

You can control the offset and number of results returned by adjusting the offset and limit query parameters. All endpoints will limit the number of results returned by the limit parameter and fallback on the allowed maximum if you request too many items. The usual maximum for offset is 50 items but may differ by endpoint.

curl -H "Authorization: Bearer $LABFOLDER_API_TOKEN" <API_RESOURCE_PATH_GOES_HERE>?limit=1000

[
    {...some JSON...},
    {...some JSON...},
    {...some JSON...},
    {...some JSON...}
]

Client Errors

Client errors are denoted as a 4XX response code. All errors will return JSON with a message attribute explaining what went wrong.

{
    "status": 400,
    "message": "Unable to parse JSON"
}

There are several types of errors:

Authentication and authorization related errors

These will return either a 401 Unauthorized on missing authentication or a 403 Forbidden on missing authorization.

Invalid requests because of invalid HTTP verbs or media types

These will return a 405 Method Not Allowed or 415 Unsupported Media Type respectively.

Missing parameters or invalid body format

A 400 Bad Request is usually returned in case of missing parameters or an invalid body format. The latter could be because of invalid JSON or the wrong object shape (e.g. wrong nesting of objects).

Validation errors

A 422 Unprocessable Entity is returned if the body format is correct but the entity did not pass validation. This denotes a wrong user input and can potentially be signalled to the user.

Timezones & Date Format

Date Format

In general the API returns and expects dates & times in the ISO 8601 format including the timezone specification. For example: 2017-02-27T17:05:06.000+0100 for a time or 2017-02-27 for a date.

Timezone

The date time will be returned in the timezone of the server.

Data Access

According to the provided authentication token the requesting user is identified.

Full List Requests

On full list requests, the returned entities always contain all user accessible data and not only the user self-created content, as far as not mentioned differently in the endpoint description.

Groups

Groups act as a container for users and projects. They allow to manage shared access for the containing contents.

The following operations are available for groups:

Groups

List Groups
GET/groups{?type,limit,offset}

Returns all the top level groups (subgroups are not returned) that user belongs to.

Example URI

GET /api/v2/groups?type=BASIC&limit=&offset=
URI Parameters
HideShow
type
string (optional) Example: BASIC

Group type to be filtered

Choices: BASIC ADVANCED

limit
number (optional) Default: 20 

Maximum number of groups to return

offset
number (optional) Default: 0 

Offset into result-set (useful for pagination)

Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
X-Total-Count: 1
X-Limit: 20
X-Offset: 0
Body
[
  {
    "title": "Luke's Private Group",
    "id": "46123",
    "owner_id": "11038",
    "description": "This is a group description",
    "type": "BASIC",
    "creation_date": "2017-02-10T12:34:56.789+0200",
    "version_date": "2017-02-15T12:34:56.789+0200",
    "settings": {
      "prevent_delete_project": false,
      "prevent_private_projects": false,
      "allow_user_in_multiple_subgroups": false,
      "prevent_export": false,
      "only_admins_create_templates": false
    }
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "description": "the display title of the group"
      },
      "id": {
        "type": "string",
        "description": "the unique id of the group"
      },
      "owner_id": {
        "type": "string",
        "description": "the id of the group owner"
      },
      "description": {
        "type": "string",
        "description": "the description of the group"
      },
      "type": {
        "type": "string",
        "enum": [
          "BASIC",
          "ADVANCED"
        ],
        "description": "the type of the group"
      },
      "creation_date": {
        "type": "string",
        "description": "date when the group was created"
      },
      "version_date": {
        "type": "string",
        "description": "date when the group was last modified"
      },
      "settings": {
        "type": "object",
        "properties": {
          "prevent_delete_project": {
            "type": "boolean",
            "description": "indicates if the project deletion is disabled for the group"
          },
          "prevent_private_projects": {
            "type": "boolean",
            "description": "indicates if the group members are allowed to create private projects"
          },
          "allow_user_in_multiple_subgroups": {
            "type": "boolean",
            "description": "indicates if group members are allowed to be in multiple subgroups"
          },
          "prevent_export": {
            "type": "boolean",
            "description": "indicates if the group members are allowed to export data"
          },
          "only_admins_create_templates": {
            "type": "boolean",
            "description": "indicates if the non-admin group members are allowed to create templates"
          }
        },
        "required": [
          "prevent_delete_project",
          "prevent_private_projects",
          "allow_user_in_multiple_subgroups",
          "prevent_export",
          "only_admins_create_templates"
        ],
        "description": "the group settings"
      }
    },
    "required": [
      "title",
      "id",
      "owner_id",
      "description",
      "type",
      "creation_date",
      "version_date",
      "settings"
    ]
  }
}

Group

Get Group
GET/groups/{id}

Returns the specified group.

Example URI

GET /api/v2/groups/1200
URI Parameters
HideShow
id
string (required) Example: 1200

id of the group

Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "title": "Luke's Private Group",
  "id": "46123",
  "owner_id": "11038",
  "description": "This is a group description",
  "type": "BASIC",
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "settings": {
    "prevent_delete_project": false,
    "prevent_private_projects": false,
    "allow_user_in_multiple_subgroups": false,
    "prevent_export": false,
    "only_admins_create_templates": false
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display title of the group"
    },
    "id": {
      "type": "string",
      "description": "the unique id of the group"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the group owner"
    },
    "description": {
      "type": "string",
      "description": "the description of the group"
    },
    "type": {
      "type": "string",
      "enum": [
        "BASIC",
        "ADVANCED"
      ],
      "description": "the type of the group"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the group was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the group was last modified"
    },
    "settings": {
      "type": "object",
      "properties": {
        "prevent_delete_project": {
          "type": "boolean",
          "description": "indicates if the project deletion is disabled for the group"
        },
        "prevent_private_projects": {
          "type": "boolean",
          "description": "indicates if the group members are allowed to create private projects"
        },
        "allow_user_in_multiple_subgroups": {
          "type": "boolean",
          "description": "indicates if group members are allowed to be in multiple subgroups"
        },
        "prevent_export": {
          "type": "boolean",
          "description": "indicates if the group members are allowed to export data"
        },
        "only_admins_create_templates": {
          "type": "boolean",
          "description": "indicates if the non-admin group members are allowed to create templates"
        }
      },
      "required": [
        "prevent_delete_project",
        "prevent_private_projects",
        "allow_user_in_multiple_subgroups",
        "prevent_export",
        "only_admins_create_templates"
      ],
      "description": "the group settings"
    }
  },
  "required": [
    "title",
    "id",
    "owner_id",
    "description",
    "type",
    "creation_date",
    "version_date",
    "settings"
  ],
  "additionalProperties": false
}

Create Group
POST/groups

Create a group

Example URI

POST /api/v2/groups
Request  Create Group with Title
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "Luke's Private Entry"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the entry"
    }
  },
  "required": [
    "title"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /groups/10945
Body
{
  "title": "Luke's Private Group",
  "id": "46123",
  "owner_id": "11038",
  "description": "This is a group description",
  "type": "BASIC",
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "settings": {
    "prevent_delete_project": false,
    "prevent_private_projects": false,
    "allow_user_in_multiple_subgroups": false,
    "prevent_export": false,
    "only_admins_create_templates": false
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display title of the group"
    },
    "id": {
      "type": "string",
      "description": "the unique id of the group"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the group owner"
    },
    "description": {
      "type": "string",
      "description": "the description of the group"
    },
    "type": {
      "type": "string",
      "enum": [
        "BASIC",
        "ADVANCED"
      ],
      "description": "the type of the group"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the group was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the group was last modified"
    },
    "settings": {
      "type": "object",
      "properties": {
        "prevent_delete_project": {
          "type": "boolean",
          "description": "indicates if the project deletion is disabled for the group"
        },
        "prevent_private_projects": {
          "type": "boolean",
          "description": "indicates if the group members are allowed to create private projects"
        },
        "allow_user_in_multiple_subgroups": {
          "type": "boolean",
          "description": "indicates if group members are allowed to be in multiple subgroups"
        },
        "prevent_export": {
          "type": "boolean",
          "description": "indicates if the group members are allowed to export data"
        },
        "only_admins_create_templates": {
          "type": "boolean",
          "description": "indicates if the non-admin group members are allowed to create templates"
        }
      },
      "required": [
        "prevent_delete_project",
        "prevent_private_projects",
        "allow_user_in_multiple_subgroups",
        "prevent_export",
        "only_admins_create_templates"
      ],
      "description": "the group settings"
    }
  },
  "required": [
    "title",
    "id",
    "owner_id",
    "description",
    "type",
    "creation_date",
    "version_date",
    "settings"
  ],
  "additionalProperties": false
}

Update Group
PUT/groups/{id}

Updates a group. The group title, description, and settings can be updated. If one of these fields or a specific group setting is not provided, it won’t be updated.

Example URI

PUT /api/v2/groups/1200
URI Parameters
HideShow
id
string (required) Example: 1200

id of the group

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "1200",
  "title": "Luke's Private Group",
  "description": "A short description about the group",
  "settings": {
    "prevent_delete_project": false,
    "prevent_private_projects": false,
    "allow_user_in_multiple_subgroups": false,
    "prevent_export": false,
    "only_admins_create_templates": false
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the id of the group"
    },
    "title": {
      "type": "string",
      "description": "the display title of the group"
    },
    "description": {
      "type": "string",
      "description": "the display title of the group"
    },
    "settings": {
      "type": "object",
      "properties": {
        "prevent_delete_project": {
          "type": "boolean",
          "description": "indicates if the project deletion is disabled for the group"
        },
        "prevent_private_projects": {
          "type": "boolean",
          "description": "indicates if the group members are allowed to create private projects"
        },
        "allow_user_in_multiple_subgroups": {
          "type": "boolean",
          "description": "indicates if group members are allowed to be in multiple subgroups"
        },
        "prevent_export": {
          "type": "boolean",
          "description": "indicates if the group members are allowed to export data"
        },
        "only_admins_create_templates": {
          "type": "boolean",
          "description": "indicates if the non-admin group members are allowed to create templates"
        }
      },
      "required": [
        "prevent_delete_project",
        "prevent_private_projects",
        "allow_user_in_multiple_subgroups",
        "prevent_export",
        "only_admins_create_templates"
      ],
      "description": "the group settings"
    }
  },
  "additionalProperties": false
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "title": "Luke's Private Group",
  "id": "46123",
  "owner_id": "11038",
  "description": "This is a group description",
  "type": "BASIC",
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "settings": {
    "prevent_delete_project": false,
    "prevent_private_projects": false,
    "allow_user_in_multiple_subgroups": false,
    "prevent_export": false,
    "only_admins_create_templates": false
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display title of the group"
    },
    "id": {
      "type": "string",
      "description": "the unique id of the group"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the group owner"
    },
    "description": {
      "type": "string",
      "description": "the description of the group"
    },
    "type": {
      "type": "string",
      "enum": [
        "BASIC",
        "ADVANCED"
      ],
      "description": "the type of the group"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the group was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the group was last modified"
    },
    "settings": {
      "type": "object",
      "properties": {
        "prevent_delete_project": {
          "type": "boolean",
          "description": "indicates if the project deletion is disabled for the group"
        },
        "prevent_private_projects": {
          "type": "boolean",
          "description": "indicates if the group members are allowed to create private projects"
        },
        "allow_user_in_multiple_subgroups": {
          "type": "boolean",
          "description": "indicates if group members are allowed to be in multiple subgroups"
        },
        "prevent_export": {
          "type": "boolean",
          "description": "indicates if the group members are allowed to export data"
        },
        "only_admins_create_templates": {
          "type": "boolean",
          "description": "indicates if the non-admin group members are allowed to create templates"
        }
      },
      "required": [
        "prevent_delete_project",
        "prevent_private_projects",
        "allow_user_in_multiple_subgroups",
        "prevent_export",
        "only_admins_create_templates"
      ],
      "description": "the group settings"
    }
  },
  "required": [
    "title",
    "id",
    "owner_id",
    "description",
    "type",
    "creation_date",
    "version_date",
    "settings"
  ],
  "additionalProperties": false
}

Get Group Tree
GET/groups/{id}/tree

Returns tree of group, it’s subgroup and members

Example URI

GET /api/v2/groups/1200/tree
URI Parameters
HideShow
id
string (required) Example: 1200

id of the group.

Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": "1200",
  "name": "Rebellion",
  "children": [
    {
      "id": "12585",
      "admin": false,
      "user": {
        "id": "3857",
        "first_name": "Luke",
        "last_name": "Skywalker",
        "email": "luke.skywalker@starwars.com",
        "deactivated": false,
        "profile_picture_hash": "abc",
        "iam_id": "d229cc70-455d-421d-9938-b2d8b4dee79e"
      },
      "type": "MEMBER"
    },
    {
      "id": "12585",
      "title": "Rogue One",
      "type": "SUBGROUP",
      "children": [
        {
          "id": "12585",
          "admin": false,
          "user": {
            "id": "3857",
            "first_name": "Luke",
            "last_name": "Skywalker",
            "email": "luke.skywalker@starwars.com",
            "deactivated": false,
            "profile_picture_hash": "abc",
            "iam_id": "d229cc70-455d-421d-9938-b2d8b4dee79e"
          },
          "type": "MEMBER"
        },
        {}
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the id of the group"
    },
    "name": {
      "type": "string",
      "description": "name of the group"
    },
    "children": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "the unique identifier of the group tree membership"
            },
            "admin": {
              "type": "boolean",
              "description": "indicator if the group member is admin in this group"
            },
            "user": {
              "type": "object",
              "properties": {
                "id": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "unique user id of the group member"
                },
                "first_name": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "first name of the member. Not defined if this member has a pending group invitation"
                },
                "last_name": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "last name of the member. Not defined if this member has a pending group invitation"
                },
                "email": {
                  "type": "string",
                  "description": "email address of the member"
                },
                "deactivated": {
                  "type": "boolean",
                  "description": "the flags shows if the user's account is deactivated"
                },
                "profile_picture_hash": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "profile picture hash for the picture url of the user"
                },
                "iam_id": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "user uuid identifying the user in IAM"
                }
              },
              "required": [
                "id",
                "first_name",
                "last_name",
                "email",
                "deactivated",
                "profile_picture_hash",
                "iam_id"
              ],
              "description": "user identity entity of the group member"
            },
            "type": {
              "type": "string",
              "enum": [
                "MEMBER"
              ],
              "description": "the type of group tree node"
            }
          },
          "required": [
            "id",
            "admin",
            "user",
            "type"
          ]
        },
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "the unique identifier of the subgroup"
            },
            "title": {
              "type": "string",
              "description": "the title of the subgroup"
            },
            "type": {
              "type": "string",
              "enum": [
                "SUBGROUP"
              ],
              "description": "the type of group tree node"
            },
            "children": {
              "type": "array",
              "items": [
                {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "the unique identifier of the group tree membership"
                    },
                    "admin": {
                      "type": "boolean",
                      "description": "indicator if the group member is admin in this group"
                    },
                    "user": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "unique user id of the group member"
                        },
                        "first_name": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "first name of the member. Not defined if this member has a pending group invitation"
                        },
                        "last_name": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "last name of the member. Not defined if this member has a pending group invitation"
                        },
                        "email": {
                          "type": "string",
                          "description": "email address of the member"
                        },
                        "deactivated": {
                          "type": "boolean",
                          "description": "the flags shows if the user's account is deactivated"
                        },
                        "profile_picture_hash": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "profile picture hash for the picture url of the user"
                        },
                        "iam_id": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "user uuid identifying the user in IAM"
                        }
                      },
                      "required": [
                        "id",
                        "first_name",
                        "last_name",
                        "email",
                        "deactivated",
                        "profile_picture_hash",
                        "iam_id"
                      ],
                      "description": "user identity entity of the group member"
                    },
                    "type": {
                      "type": "string",
                      "enum": [
                        "MEMBER"
                      ],
                      "description": "the type of group tree node"
                    }
                  },
                  "required": [
                    "id",
                    "admin",
                    "user",
                    "type"
                  ]
                },
                {
                  "type": "object",
                  "properties": {}
                }
              ],
              "description": "child members and subgroups will be represented recursively"
            }
          },
          "required": [
            "id",
            "title",
            "type"
          ]
        }
      ],
      "description": "child members and subgroups will be represented recursively"
    }
  },
  "required": [
    "id",
    "name",
    "children"
  ],
  "additionalProperties": false
}

Subgroups

List Subgroups
GET/groups/{id}/subgroups{?parent_id,only_root_level,limit,offset}

Returns subgroups of the group

Example URI

GET /api/v2/groups/1200/subgroups?parent_id=&only_root_level=&limit=&offset=
URI Parameters
HideShow
id
string (required) Example: 1200

id of the group

parent_id
string (optional) 

Only return subgroups that reside within the specified subgroup

only_root_level
boolean (optional) Default: false 

Only return root (top) level subgroups - I.e. subgroups that do not reside within a subgroup

limit
number (optional) Default: 20 

Maximum number of subgroups to return

offset
number (optional) Default: 0 

Offset into result-set (useful for pagination)

Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
[
  {
    "id": "12585",
    "title": "Rogue One",
    "group_id": "1200",
    "parent_id": "12587"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "the unique identifier of the subgroup"
      },
      "title": {
        "type": "string",
        "description": "the title of the subgroup"
      },
      "group_id": {
        "type": "string",
        "description": "the id of the group this subgroup is part of"
      },
      "parent_id": {
        "type": [
          "string",
          "null"
        ],
        "description": "the subgroup id to which this subgroup is subordinate"
      }
    },
    "required": [
      "id",
      "title",
      "group_id",
      "parent_id"
    ]
  }
}

Update Subgroup
PATCH/groups/{id}/subgroups/{subgroupId}

This endpoint complies with RFC 6902, the specification for JSON Patch.

  • Update a subgroup’s name.

The supported operations will grow in time.

Example URI

PATCH /api/v2/groups/1207/subgroups/237
URI Parameters
HideShow
id
string (required) Example: 1207

the unique id of the group

subgroupId
string (required) Example: 237

the unique id of the subgroup

Request  Change Subgroup Name
HideShow
Headers
Content-Type: application/json-patch+json
Body
[
  {
    "op": "replace",
    "path": "/name",
    "value": "New Subgroup Name"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "op": {
        "type": "string",
        "enum": [
          "replace"
        ],
        "description": "The replace operation defined by RFC 6902"
      },
      "path": {
        "type": "string",
        "enum": [
          "/name"
        ],
        "description": "JSON Pointer notation to the field that holds the subgroup name"
      },
      "value": {
        "type": "string",
        "description": "the name of the subgroup"
      }
    },
    "required": [
      "op",
      "path",
      "value"
    ]
  }
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": "237",
  "title": "New Subgroup Name",
  "group_id": "1207",
  "parent_id": "null"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the unique identifier of the subgroup"
    },
    "title": {
      "type": "string",
      "description": "the title of the subgroup"
    },
    "group_id": {
      "type": "string",
      "description": "the id of the group this subgroup is part of"
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the subgroup id to which this subgroup is subordinate"
    }
  },
  "required": [
    "id",
    "title",
    "group_id",
    "parent_id"
  ],
  "additionalProperties": false
}

Group Memberships

List Group Memberships
GET/groups/{id}/memberships{?subgroup_id,user_id,project_ids,project_folder_ids,only_root_level,username,include_pending,limit,offset}

Returns memberships of users in a group

Example URI

GET /api/v2/groups/1200/memberships?subgroup_id=234&user_id=11040&project_ids=36275&project_folder_ids=36274&only_root_level=true&username=Han&include_pending=true&limit=&offset=
URI Parameters
HideShow
id
string (required) Example: 1200

id of the group

subgroup_id
string (optional) Example: 234

Only return group members that reside within the specified subgroup

user_id
string (optional) Example: 11040

Only return membership information for the specified user

project_ids
string (optional) Example: 36275

Comma separated list of project ids that have to be accessible for the group members

project_folder_ids
string (optional) Example: 36274

Comma separated list of project folder ids that have to be accessible for the group members

only_root_level
boolean (optional) Default: false Example: true

Only return root (top) level group members - I.e. members that do not reside within a subgroup

username
string (optional) Example: Han

A search string to filter group members by email, first name or last name

include_pending
boolean (optional) Default: false Example: true

[beta] Include the pending group invitations in the result

limit
number (optional) Default: 20 

Maximum number of group members to return - Maximum allowed value is 100

offset
number (optional) Default: 0 

Offset into result-set (useful for pagination)

Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
[
  {
    "id": "12585",
    "group_id": "1200",
    "subgroup_id": "12587",
    "admin": false,
    "user": {
      "id": "3857",
      "first_name": "Luke",
      "last_name": "Skywalker",
      "email": "luke.skywalker@starwars.com",
      "deactivated": false,
      "profile_picture_hash": "bhOwHTKEjrPTDeiMtTnc",
      "iam_id": "d229cc70-455d-421d-9938-b2d8b4dee79e"
    }
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "the unique identifier of the group membership"
      },
      "group_id": {
        "type": "string",
        "description": "the id of the group this member belongs to"
      },
      "subgroup_id": {
        "type": [
          "string",
          "null"
        ],
        "description": "the id of the subgroup this member belongs to"
      },
      "admin": {
        "type": "boolean",
        "description": "indicator if the group member is admin in this group"
      },
      "user": {
        "type": "object",
        "properties": {
          "id": {
            "type": [
              "string",
              "null"
            ],
            "description": "unique user id of the group member"
          },
          "first_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "first name of the member. Not defined if this member has a pending group invitation"
          },
          "last_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "last name of the member. Not defined if this member has a pending group invitation"
          },
          "email": {
            "type": "string",
            "description": "email address of the member"
          },
          "deactivated": {
            "type": "boolean",
            "description": "the flags shows if the user's account is deactivated"
          },
          "profile_picture_hash": {
            "type": [
              "string",
              "null"
            ],
            "description": "a hash to be used for the profile picture location url"
          },
          "iam_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "user uuid identifying the user in IAM"
          }
        },
        "required": [
          "id",
          "first_name",
          "last_name",
          "email",
          "deactivated",
          "profile_picture_hash",
          "iam_id"
        ],
        "description": "user identity entity of the group member"
      }
    },
    "required": [
      "id",
      "group_id",
      "subgroup_id",
      "admin",
      "user"
    ]
  }
}

Get Group Membership
GET/group-memberships/{id}

Returns the specified group membership

Example URI

GET /api/v2/group-memberships/3132
URI Parameters
HideShow
id
string (required) Example: 3132

id of the group membership

Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": "12585",
  "group_id": "1200",
  "subgroup_id": "12587",
  "admin": false,
  "user": {
    "id": "3857",
    "first_name": "Luke",
    "last_name": "Skywalker",
    "email": "luke.skywalker@starwars.com",
    "deactivated": false,
    "profile_picture_hash": "bhOwHTKEjrPTDeiMtTnc",
    "iam_id": "d229cc70-455d-421d-9938-b2d8b4dee79e"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the unique identifier of the group membership"
    },
    "group_id": {
      "type": "string",
      "description": "the id of the group this member belongs to"
    },
    "subgroup_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the subgroup this member belongs to"
    },
    "admin": {
      "type": "boolean",
      "description": "indicator if the group member is admin in this group"
    },
    "user": {
      "type": "object",
      "properties": {
        "id": {
          "type": [
            "string",
            "null"
          ],
          "description": "unique user id of the group member"
        },
        "first_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "first name of the member. Not defined if this member has a pending group invitation"
        },
        "last_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "last name of the member. Not defined if this member has a pending group invitation"
        },
        "email": {
          "type": "string",
          "description": "email address of the member"
        },
        "deactivated": {
          "type": "boolean",
          "description": "the flags shows if the user's account is deactivated"
        },
        "profile_picture_hash": {
          "type": [
            "string",
            "null"
          ],
          "description": "a hash to be used for the profile picture location url"
        },
        "iam_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "user uuid identifying the user in IAM"
        }
      },
      "required": [
        "id",
        "first_name",
        "last_name",
        "email",
        "deactivated",
        "profile_picture_hash",
        "iam_id"
      ],
      "description": "user identity entity of the group member"
    }
  },
  "required": [
    "id",
    "group_id",
    "subgroup_id",
    "admin",
    "user"
  ],
  "additionalProperties": false
}

Create Group Membership
POST/group-memberships

Create a new group membership. This is how new group members may be invited to a group or subgroup.

Example URI

POST /api/v2/group-memberships
Request  Create new group membership in group
HideShow
Headers
Content-Type: application/json
Body
{
  "email": "princess.leia@starwars.com",
  "group_id": "1203"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "The email of the person to invite to your group"
    },
    "group_id": {
      "type": "string",
      "description": "The group id"
    }
  },
  "required": [
    "email",
    "group_id"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /group-memberships/12585
Body
{
  "id": "12585",
  "group_id": "1200",
  "subgroup_id": "12587",
  "admin": false,
  "user": {
    "id": "3857",
    "first_name": "Luke",
    "last_name": "Skywalker",
    "email": "luke.skywalker@starwars.com",
    "deactivated": false,
    "profile_picture_hash": "bhOwHTKEjrPTDeiMtTnc",
    "iam_id": "d229cc70-455d-421d-9938-b2d8b4dee79e"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the unique identifier of the group membership"
    },
    "group_id": {
      "type": "string",
      "description": "the id of the group this member belongs to"
    },
    "subgroup_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the subgroup this member belongs to"
    },
    "admin": {
      "type": "boolean",
      "description": "indicator if the group member is admin in this group"
    },
    "user": {
      "type": "object",
      "properties": {
        "id": {
          "type": [
            "string",
            "null"
          ],
          "description": "unique user id of the group member"
        },
        "first_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "first name of the member. Not defined if this member has a pending group invitation"
        },
        "last_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "last name of the member. Not defined if this member has a pending group invitation"
        },
        "email": {
          "type": "string",
          "description": "email address of the member"
        },
        "deactivated": {
          "type": "boolean",
          "description": "the flags shows if the user's account is deactivated"
        },
        "profile_picture_hash": {
          "type": [
            "string",
            "null"
          ],
          "description": "a hash to be used for the profile picture location url"
        },
        "iam_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "user uuid identifying the user in IAM"
        }
      },
      "required": [
        "id",
        "first_name",
        "last_name",
        "email",
        "deactivated",
        "profile_picture_hash",
        "iam_id"
      ],
      "description": "user identity entity of the group member"
    }
  },
  "required": [
    "id",
    "group_id",
    "subgroup_id",
    "admin",
    "user"
  ],
  "additionalProperties": false
}
Request  Create new group membership in subgroup
HideShow
Headers
Content-Type: application/json
Body
{
  "email": "han.solo@starwars.com",
  "group_id": "1203",
  "subgroup_id": "235"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "The email of the person to invite to your group"
    },
    "group_id": {
      "type": "string",
      "description": "The group id"
    },
    "subgroup_id": {
      "type": "string",
      "description": "id of the subgroup to which the member is added"
    }
  },
  "required": [
    "email",
    "group_id",
    "subgroup_id"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /group-memberships/12585
Body
{
  "id": "12585",
  "group_id": "1200",
  "subgroup_id": "12587",
  "admin": false,
  "user": {
    "id": "3857",
    "first_name": "Luke",
    "last_name": "Skywalker",
    "email": "luke.skywalker@starwars.com",
    "deactivated": false,
    "profile_picture_hash": "bhOwHTKEjrPTDeiMtTnc",
    "iam_id": "d229cc70-455d-421d-9938-b2d8b4dee79e"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the unique identifier of the group membership"
    },
    "group_id": {
      "type": "string",
      "description": "the id of the group this member belongs to"
    },
    "subgroup_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the subgroup this member belongs to"
    },
    "admin": {
      "type": "boolean",
      "description": "indicator if the group member is admin in this group"
    },
    "user": {
      "type": "object",
      "properties": {
        "id": {
          "type": [
            "string",
            "null"
          ],
          "description": "unique user id of the group member"
        },
        "first_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "first name of the member. Not defined if this member has a pending group invitation"
        },
        "last_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "last name of the member. Not defined if this member has a pending group invitation"
        },
        "email": {
          "type": "string",
          "description": "email address of the member"
        },
        "deactivated": {
          "type": "boolean",
          "description": "the flags shows if the user's account is deactivated"
        },
        "profile_picture_hash": {
          "type": [
            "string",
            "null"
          ],
          "description": "a hash to be used for the profile picture location url"
        },
        "iam_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "user uuid identifying the user in IAM"
        }
      },
      "required": [
        "id",
        "first_name",
        "last_name",
        "email",
        "deactivated",
        "profile_picture_hash",
        "iam_id"
      ],
      "description": "user identity entity of the group member"
    }
  },
  "required": [
    "id",
    "group_id",
    "subgroup_id",
    "admin",
    "user"
  ],
  "additionalProperties": false
}

Delete Group Membership
DELETE/group-memberships/{id}

Delete a group membership. This endpoint can be used to:

  • leave a group, either on their own accord, or by a group admin.

  • decline a membership invitation

In order to be removed from a group, a user must have no project, template, or folder ownership within the group context.

Example URI

DELETE /api/v2/group-memberships/3135
URI Parameters
HideShow
id
string (required) Example: 3135

id of the group membership

Response  204

Projects

Projects act as a container for entries and are used to manage shared access for the containing entries.

The following operations are available for projects:

Projects

List Projects
GET/projects{?group_id,group_ids,owner_id,owner_ids,only_root_level,folder_id,project_ids,title,private_projects_only,creation_date_from,creation_date_to,modification_date_from,modification_date_to,include_hidden,access_role,expand,limit,offset}

Returns a list of projects the user has access to.

Example URI

GET /api/v2/projects?group_id=1200&group_ids=1200,1201&owner_id=11038&owner_ids=11038,11039&only_root_level=true&folder_id=36274&project_ids=36279&title=My project&private_projects_only=true&creation_date_from=2023-02-08&creation_date_to=2023-02-09&modification_date_from=2023-02-08&modification_date_to=2023-02-09&include_hidden=false&access_role=&expand=owner&limit=&offset=
URI Parameters
HideShow
group_id
string (optional) Example: 1200

Only return projects that belong to the specified group. Please note that this param is deprecated and will removed in the future. Its usage shall be replaced with group_ids, which is a comma separated list that contains one or more group IDs.

group_ids
string (optional) Example: 1200,1201

Only return projects that belong to the specified groups (comma separated list)

owner_id
string (optional) Example: 11038

Only return projects that are owned by the given user. Please note that this param is deprecated and will removed in the future. Its usage shall be replaced with owner_ids, which is a comma separated list that contains one or more user IDs.

owner_ids
string (optional) Example: 11038,11039

Only return projects that are owned by the given users (comma separated list)

only_root_level
boolean (optional) Default: false Example: true

Only return root (top) level projects - I.e. projects that do not reside within a folder

folder_id
string (optional) Example: 36274

Only return projects that reside within the specified folder

project_ids
string (optional) Example: 36279

A comma separated list of project ids specifying the projects to be returned

title
string (optional) Example: My project

Only return projects with a title containing this string

private_projects_only
boolean (optional) Example: true

Only return the user’s private projects

creation_date_from
date (optional) Example: 2023-02-08

Only return projects that were created past or at the specified date

creation_date_to
date (optional) Example: 2023-02-09

Only return projects that were created before or at the specified date

modification_date_from
date (optional) Example: 2023-02-08

Only return projects that were edited past or at the specified date

modification_date_to
date (optional) Example: 2023-02-09

Only return projects that were edited before or at the specified date

include_hidden
boolean (optional) Default: false Example: false

Flag to include hidden projects

access_role
enum (optional) 

Only return projects that the user has access with a specific role. If not provided, all projects the user has access to will be returned.

Choices: ADMIN SUBGROUP_ADMIN OWNER USER

expand
string (optional) Example: owner

A comma separated list of related domain objects that should be expanded for all items returned

Choices: owner

limit
number (optional) Default: 20 

Maximum number of projects to return - Maximum allowed limit is 100

offset
number (optional) Default: 0 

Offset into result-set (useful for pagination)

Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
X-Total-Count: 1
X-Limit: 20
X-Offset: 0
Body
[
  {
    "title": "Luke's Private Project",
    "id": "46123",
    "owner_id": "11038",
    "group_id": "null",
    "folder_id": "null",
    "hidden": false,
    "creation_date": "2017-02-10T12:34:56.789+0200",
    "version_date": "2017-02-15T12:34:56.789+0200",
    "collaborative": false,
    "number_of_entries": 1
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "description": "the display name of the project"
      },
      "id": {
        "type": "string",
        "description": "the unique id of the project"
      },
      "owner_id": {
        "type": "string",
        "description": "the id of the project owner"
      },
      "group_id": {
        "type": [
          "string",
          "null"
        ],
        "description": "the id of the group to which the project is associated, null is used for the private projects"
      },
      "folder_id": {
        "type": [
          "string",
          "null"
        ],
        "description": "the id of the closest accessible parent folder in which the project is located. null is used projects which are not in a parent folder or don't have closest accessible parent folder"
      },
      "hidden": {
        "type": "boolean",
        "description": "indicating if the project is hidden"
      },
      "creation_date": {
        "type": "string",
        "description": "date when the project was created"
      },
      "version_date": {
        "type": "string",
        "description": "date when the project was last modified"
      },
      "collaborative": {
        "type": "boolean",
        "description": "boolean flag indicating whether the project is collaborative. when this is true, every entry within this project can be edited by all project members instead of by its author only. a project only shows as collaborative when the multi-author feature is enabled. its value is always false when the feature is disabled."
      },
      "number_of_entries": {
        "type": "number",
        "description": "number of entries in the project"
      }
    },
    "required": [
      "title",
      "id",
      "owner_id",
      "group_id",
      "folder_id",
      "hidden",
      "creation_date",
      "version_date",
      "collaborative",
      "number_of_entries"
    ]
  }
}

Create Project
POST/projects

Create a project

Example URI

POST /api/v2/projects
Request  Create Private Project
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "Luke's Private Project"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the project"
    }
  },
  "required": [
    "title"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /projects/1234
Body
{
  "title": "Luke's Private Project",
  "id": "46123",
  "owner_id": "11038",
  "group_id": "null",
  "folder_id": "null",
  "hidden": false,
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "collaborative": false,
  "number_of_entries": 1
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the project"
    },
    "id": {
      "type": "string",
      "description": "the unique id of the project"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the project owner"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the group to which the project is associated, null is used for the private projects"
    },
    "folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the closest accessible parent folder in which the project is located. null is used projects which are not in a parent folder or don't have closest accessible parent folder"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the project is hidden"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the project was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the project was last modified"
    },
    "collaborative": {
      "type": "boolean",
      "description": "boolean flag indicating whether the project is collaborative. when this is true, every entry within this project can be edited by all project members instead of by its author only. a project only shows as collaborative when the multi-author feature is enabled. its value is always false when the feature is disabled."
    },
    "number_of_entries": {
      "type": "number",
      "description": "number of entries in the project"
    }
  },
  "required": [
    "title",
    "id",
    "owner_id",
    "group_id",
    "folder_id",
    "hidden",
    "creation_date",
    "version_date",
    "collaborative",
    "number_of_entries"
  ]
}
Request  Create Private Project in a Folder
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "Luke's Private Project",
  "folder_id": "36273"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the project"
    },
    "folder_id": {
      "type": "string",
      "description": "the id of the folder in which the project is stored"
    }
  },
  "required": [
    "title",
    "folder_id"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /projects/1234
Body
{
  "title": "Luke's Private Project",
  "id": "46123",
  "owner_id": "11038",
  "group_id": "null",
  "folder_id": "36273",
  "hidden": false,
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "collaborative": false,
  "number_of_entries": 1
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the project"
    },
    "id": {
      "type": "string",
      "description": "the unique id of the project"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the project owner"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the group to which the project is associated, null is used for the private projects"
    },
    "folder_id": {
      "type": "string",
      "description": "the id of the folder in which the project is stored"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the project is hidden"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the project was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the project was last modified"
    },
    "collaborative": {
      "type": "boolean",
      "description": "boolean flag indicating whether the project is collaborative. when this is true, every entry within this project can be edited by all project members instead of by its author only. a project only shows as collaborative when the multi-author feature is enabled. its value is always false when the feature is disabled."
    },
    "number_of_entries": {
      "type": "number",
      "description": "number of entries in the project"
    }
  },
  "required": [
    "title",
    "id",
    "owner_id",
    "group_id",
    "folder_id",
    "hidden",
    "creation_date",
    "version_date",
    "collaborative",
    "number_of_entries"
  ]
}
Request  Create Group Project
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "Luke's Private Project",
  "group_id": "1200"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the project"
    },
    "group_id": {
      "type": "string",
      "description": "the id of the group to which the project is associated"
    }
  },
  "required": [
    "title",
    "group_id"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /projects/1234
Body
{
  "title": "Luke's Private Project",
  "id": "46123",
  "owner_id": "11038",
  "group_id": "1200",
  "folder_id": "null",
  "hidden": false,
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "collaborative": false,
  "number_of_entries": 1
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the project"
    },
    "id": {
      "type": "string",
      "description": "the unique id of the project"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the project owner"
    },
    "group_id": {
      "type": "string",
      "description": "the id of the group to which the project is associated"
    },
    "folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the closest accessible parent folder in which the project is located. null is used projects which are not in a parent folder or don't have closest accessible parent folder"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the project is hidden"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the project was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the project was last modified"
    },
    "collaborative": {
      "type": "boolean",
      "description": "boolean flag indicating whether the project is collaborative. when this is true, every entry within this project can be edited by all project members instead of by its author only. a project only shows as collaborative when the multi-author feature is enabled. its value is always false when the feature is disabled."
    },
    "number_of_entries": {
      "type": "number",
      "description": "number of entries in the project"
    }
  },
  "required": [
    "title",
    "id",
    "owner_id",
    "group_id",
    "folder_id",
    "hidden",
    "creation_date",
    "version_date",
    "collaborative",
    "number_of_entries"
  ]
}
Request  Create Group Project in a Folder
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "Luke's Private Project",
  "folder_id": "36274",
  "group_id": "1200"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the project"
    },
    "folder_id": {
      "type": "string",
      "description": "the id of the folder in which the project is stored"
    },
    "group_id": {
      "type": "string",
      "description": "the id of the group to which the project is associated"
    }
  },
  "required": [
    "title",
    "folder_id",
    "group_id"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /projects/1234
Body
{
  "title": "Luke's Private Project",
  "id": "46123",
  "owner_id": "11038",
  "group_id": "1200",
  "folder_id": "36273",
  "hidden": false,
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "collaborative": false,
  "number_of_entries": 1
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the project"
    },
    "id": {
      "type": "string",
      "description": "the unique id of the project"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the project owner"
    },
    "group_id": {
      "type": "string",
      "description": "the id of the group to which the project is associated"
    },
    "folder_id": {
      "type": "string",
      "description": "the id of the folder in which the project is stored"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the project is hidden"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the project was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the project was last modified"
    },
    "collaborative": {
      "type": "boolean",
      "description": "boolean flag indicating whether the project is collaborative. when this is true, every entry within this project can be edited by all project members instead of by its author only. a project only shows as collaborative when the multi-author feature is enabled. its value is always false when the feature is disabled."
    },
    "number_of_entries": {
      "type": "number",
      "description": "number of entries in the project"
    }
  },
  "required": [
    "title",
    "id",
    "owner_id",
    "group_id",
    "folder_id",
    "hidden",
    "creation_date",
    "version_date",
    "collaborative",
    "number_of_entries"
  ]
}

Update Project
PATCH/projects/{id}

This endpoint complies with RFC 6902, the specification for JSON Patch.

  • Update a project’s owner.

  • Update a project parent folder given it’s id and return the modified objects.

  • Update a project’s visibility, meaning hiding and unhiding projects.

The supported operations will grow in time.

Example URI

PATCH /api/v2/projects/36275
URI Parameters
HideShow
id
string (required) Example: 36275

the unique id of the project

Request  Change Project Owner
HideShow

Please note that, for change owner operation, the ‘value’ of the patch operation should be the new owner membership id, not the new owner id.

Headers
Content-Type: application/json-patch+json
Body
[
  {
    "op": "replace",
    "path": "/owner_id",
    "value": "3130"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "op": {
        "type": "string",
        "enum": [
          "replace"
        ],
        "description": "The replace operation defined by RFC 6902"
      },
      "path": {
        "type": "string",
        "enum": [
          "/owner_id"
        ],
        "description": "JSON Pointer notation to the owner of the project"
      },
      "value": {
        "type": "string",
        "description": "the unique identifier of the group membership of the new owner"
      }
    },
    "required": [
      "op",
      "path",
      "value"
    ]
  }
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "title": "Luke's Private Project",
  "id": "46123",
  "owner_id": "11038",
  "group_id": "null",
  "folder_id": "null",
  "hidden": false,
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "collaborative": false,
  "number_of_entries": 1
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the project"
    },
    "id": {
      "type": "string",
      "description": "the unique id of the project"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the project owner"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the group to which the project is associated, null is used for the private projects"
    },
    "folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the closest accessible parent folder in which the project is located. null is used projects which are not in a parent folder or don't have closest accessible parent folder"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the project is hidden"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the project was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the project was last modified"
    },
    "collaborative": {
      "type": "boolean",
      "description": "boolean flag indicating whether the project is collaborative. when this is true, every entry within this project can be edited by all project members instead of by its author only. a project only shows as collaborative when the multi-author feature is enabled. its value is always false when the feature is disabled."
    },
    "number_of_entries": {
      "type": "number",
      "description": "number of entries in the project"
    }
  },
  "required": [
    "title",
    "id",
    "owner_id",
    "group_id",
    "folder_id",
    "hidden",
    "creation_date",
    "version_date",
    "collaborative",
    "number_of_entries"
  ],
  "additionalProperties": false
}
Request  Move Project to another folder
HideShow
Headers
Content-Type: application/json-patch+json
Body
[
  {
    "op": "replace",
    "path": "/folder_id",
    "value": "36284"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "op": {
        "type": "string",
        "enum": [
          "replace"
        ],
        "description": "The replace operation defined by RFC 6902"
      },
      "path": {
        "type": "string",
        "enum": [
          "/folder_id"
        ],
        "description": "JSON Pointer notation to the folder the mentioned project will be moved into"
      },
      "value": {
        "type": "string",
        "description": "id of the new parent folder. In case of root folder, the value should be `0`."
      }
    },
    "required": [
      "op",
      "path",
      "value"
    ]
  }
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "title": "Luke's Private Project",
  "id": "46123",
  "owner_id": "11038",
  "group_id": "null",
  "folder_id": "null",
  "hidden": false,
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "collaborative": false,
  "number_of_entries": 1
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the project"
    },
    "id": {
      "type": "string",
      "description": "the unique id of the project"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the project owner"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the group to which the project is associated, null is used for the private projects"
    },
    "folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the closest accessible parent folder in which the project is located. null is used projects which are not in a parent folder or don't have closest accessible parent folder"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the project is hidden"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the project was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the project was last modified"
    },
    "collaborative": {
      "type": "boolean",
      "description": "boolean flag indicating whether the project is collaborative. when this is true, every entry within this project can be edited by all project members instead of by its author only. a project only shows as collaborative when the multi-author feature is enabled. its value is always false when the feature is disabled."
    },
    "number_of_entries": {
      "type": "number",
      "description": "number of entries in the project"
    }
  },
  "required": [
    "title",
    "id",
    "owner_id",
    "group_id",
    "folder_id",
    "hidden",
    "creation_date",
    "version_date",
    "collaborative",
    "number_of_entries"
  ],
  "additionalProperties": false
}
Request  Change Project Visibility
HideShow
Headers
Content-Type: application/json-patch+json
Body
[
  {
    "op": "replace",
    "path": "/hidden",
    "value": false
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "op": {
        "type": "string",
        "enum": [
          "replace"
        ],
        "description": "The replace operation defined by RFC 6902"
      },
      "path": {
        "type": "string",
        "enum": [
          "/hidden"
        ],
        "description": "JSON Pointer notation to the whether the project is hidden"
      },
      "value": {
        "type": "boolean",
        "description": "a boolean indicating whether the project should be hidden"
      }
    },
    "required": [
      "op",
      "path",
      "value"
    ]
  }
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "title": "Luke's Private Project",
  "id": "46123",
  "owner_id": "11038",
  "group_id": "null",
  "folder_id": "null",
  "hidden": false,
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "collaborative": false,
  "number_of_entries": 1
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the project"
    },
    "id": {
      "type": "string",
      "description": "the unique id of the project"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the project owner"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the group to which the project is associated, null is used for the private projects"
    },
    "folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the closest accessible parent folder in which the project is located. null is used projects which are not in a parent folder or don't have closest accessible parent folder"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the project is hidden"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the project was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the project was last modified"
    },
    "collaborative": {
      "type": "boolean",
      "description": "boolean flag indicating whether the project is collaborative. when this is true, every entry within this project can be edited by all project members instead of by its author only. a project only shows as collaborative when the multi-author feature is enabled. its value is always false when the feature is disabled."
    },
    "number_of_entries": {
      "type": "number",
      "description": "number of entries in the project"
    }
  },
  "required": [
    "title",
    "id",
    "owner_id",
    "group_id",
    "folder_id",
    "hidden",
    "creation_date",
    "version_date",
    "collaborative",
    "number_of_entries"
  ],
  "additionalProperties": false
}

Update Project Access
PUT/projects/{id}/access

Update the access settings of a project.
A project can be either shared with specific members, subgroups or with the whole group. Sharing it with subgroups or the group will automatically enable access for any new member joining these group structures. The project owner is always added to the access settings membership IDs automatically, to guarantee that she has access at any time.

If the project is located in a folder, all access settings of that folder will cascade to the respective project, even if you do not provide those within your request. This means the response might slightly differ from the request for this and other reasons mentioned above.

Example URI

PUT /api/v2/projects/36275/access
URI Parameters
HideShow
id
string (required) Example: 36275

id of the project

Request  Update Project Access
HideShow
Headers
Content-Type: application/json
Body
{
  "project_id": "36275",
  "group_membership_ids": [
    "3127",
    "3129"
  ],
  "subgroup_ids": [
    "234"
  ],
  "full_group_access": false,
  "collaborative": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "id of the project"
    },
    "group_membership_ids": {
      "type": "array",
      "items": [
        {
          "type": "string"
        },
        {
          "type": "string"
        }
      ],
      "description": "ids of memberships that have access to the project granted"
    },
    "subgroup_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "ids of subgroups which members have access to the project granted"
    },
    "full_group_access": {
      "type": "boolean",
      "description": "boolean flag indicating if all group members have access to the project granted. if this has value 'true', it makes setting the id fields obsolete."
    },
    "collaborative": {
      "type": "boolean",
      "description": "boolean flag indicating whether the project should be collaborative. when this is true, every entry within this project can be edited by all project members instead of by its author only. its default value is false. making a project collaborative is only possible when the multi-author feature is enabled. its value is always false when the feature is disabled."
    }
  },
  "required": [
    "project_id",
    "group_membership_ids",
    "subgroup_ids",
    "full_group_access"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "project_id": "36275",
  "group_membership_ids": [
    "3127",
    "3129"
  ],
  "subgroup_ids": [
    "234"
  ],
  "full_group_access": false,
  "collaborative": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "id of the project"
    },
    "group_membership_ids": {
      "type": "array",
      "items": [
        {
          "type": "string"
        },
        {
          "type": "string"
        }
      ],
      "description": "ids of memberships that have access to the project granted"
    },
    "subgroup_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "ids of subgroups which members have access to the project granted"
    },
    "full_group_access": {
      "type": "boolean",
      "description": "boolean flag indicating if all group members have access to the project granted. if this has value 'true', it makes setting the id fields obsolete."
    },
    "collaborative": {
      "type": "boolean",
      "description": "boolean flag indicating whether the project should be collaborative. when this is true, every entry within this project can be edited by all project members instead of by its author only. its default value is false. making a project collaborative is only possible when the multi-author feature is enabled. its value is always false when the feature is disabled."
    }
  },
  "required": [
    "project_id",
    "group_membership_ids",
    "subgroup_ids",
    "full_group_access"
  ],
  "additionalProperties": false
}

Delete Project
DELETE/projects/{id}

Delete a project

Example URI

DELETE /api/v2/projects/36286
URI Parameters
HideShow
id
string (required) Example: 36286

id of the project

Response  204

Project Filters

List Project Filters
GET/project-filters{?group_id,title,include_hidden,folder_id,search_by_ids,entry_owner_ids,entry_subgroup_ids,entry_tag_ids,limit,offset}

[beta] Returns a list of projects and project folders that the user has access to. When both folder_id and title are provided, the response will include only values matching both requirements. The response object will include a path field when the request includes the search_by_ids or title parameter.

Example URI

GET /api/v2/project-filters?group_id=1200&title=My project&include_hidden=false&folder_id=36274&search_by_ids=36274,36288&entry_owner_ids=300,301&entry_subgroup_ids=400,401&entry_tag_ids=500,501&limit=&offset=
URI Parameters
HideShow
group_id
string (required) Example: 1200

Only return projects/folders that belong to the specified group.

folder_id
string (optional) Example: 36274

Only return projects/folders that reside within the specified folder. Returns the root folder if the parameter is set to 0.

search_by_ids
string (optional) Example: 36274,36288

A comma separated list of one or more project/folder ids. If provided, the response will include Project ids matching these specific ids. Note that this parameter cannot be used in conjunction with the title parameter.

entry_owner_ids
string (optional) Example: 300,301

A comma separated list of one or more user ids. If provided, the response will include Project ids of Entries owned by these specific Users.

entry_subgroup_ids
string (optional) Example: 400,401

A comma separated list of one or more subgroups ids. If provided, the response will include Project ids of Entries owned by the Users in the provided Subgroups

title
string (optional) Example: My project

Only return projects/folders with a title containing this string. Note that this parameter cannot be used in conjunction with the search_by_ids parameter.

entry_tag_ids
string (optional) Example: 500,501

A comma separated list of one or more tag ids. If provided, the response will include Project ids of Entries having the specified tag or custom date ids.

include_hidden
boolean (optional) Default: false Example: false

Flag to include hidden projects/folders

limit
number (optional) Default: 20 

Maximum number of projects/folders to return

offset
number (optional) Default: 0 

Offset into result-set (useful for pagination)

Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
X-Total-Count: 1
X-Limit: 20
X-Offset: 0
Body
[
  {
    "id": "46123",
    "title": "Luke's Private Project",
    "is_folder": false,
    "path": [
      "46121",
      "46122"
    ],
    "number_of_projects": 1
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "the unique id of the project/folder"
      },
      "title": {
        "type": "string",
        "description": "the display name of the project"
      },
      "is_folder": {
        "type": "boolean",
        "description": "indicating if the entity is a folder"
      },
      "path": {
        "type": [
          "array",
          "null"
        ],
        "items": [
          {
            "type": "string"
          },
          {
            "type": "string"
          }
        ],
        "description": "an ordered list of folder ids that lead to this project or folder"
      },
      "number_of_projects": {
        "type": [
          "number",
          "null"
        ],
        "description": "the total number of projects in the folder (and its subfolders)"
      }
    },
    "required": [
      "id",
      "title",
      "is_folder"
    ]
  }
}

Folders

Folders are used to organize projects hierarchically.

Folders

List Folders
GET/folders{?group_id,group_ids,owner_id,owner_ids,only_root_level,content_type,parent_folder_id,folder_ids,title,private_folders_only,creation_date_from,creation_date_to,modification_date_from,modification_date_to,include_hidden,access_role,expand,limit,offset}

Returns a list of folders the user has access to.

Example URI

GET /api/v2/folders?group_id=1200&group_ids=1200,1201&owner_id=11038&owner_ids=11038,11039&only_root_level=true&content_type=&parent_folder_id=36274&folder_ids=36278&title=My folder&private_folders_only=true&creation_date_from=2023-02-08&creation_date_to=2023-02-09&modification_date_from=2023-02-08&modification_date_to=2023-02-09&include_hidden=false&access_role=&expand=owner&limit=&offset=
URI Parameters
HideShow
group_id
string (optional) Example: 1200

Only return folders that belong to the specified group. Please note that this param is deprecated and will removed in the future. Its usage shall be replaced with group_ids, which is a comma separated list that contains one or more group IDs.

group_ids
string (optional) Example: 1200,1201

Only return folders that belong to the specified groups (comma separated list)

owner_id
string (optional) Example: 11038

Only return folders that are owned by the given user. Please note that this param is deprecated and will removed in the future. Its usage shall be replaced with owner_ids, which is a comma separated list that contains one or more user IDs.

owner_ids
string (optional) Example: 11038,11039

Only return folders that are owned by the given users (comma separated list)

only_root_level
boolean (optional) Default: false Example: true

Only return root (top) level folders - I.e. folders that do not reside within another folder

content_type
string (optional) Default: PROJECTS 

The desired type of folders to retrieve

Choices: PROJECTS TEMPLATES

parent_folder_id
string (optional) Example: 36274

Only return folders that reside within the specified folder

folder_ids
string (optional) Example: 36278

A comma separated list of project ids specifying the projects to be returned

title
string (optional) Example: My folder

Only return folders with a title containing this string

private_folders_only
boolean (optional) Example: true

Only return the user’s private folders

creation_date_from
date (optional) Example: 2023-02-08

Only return folders that were created past or at the specified date

creation_date_to
date (optional) Example: 2023-02-09

Only return folders that were created before or at the specified date

modification_date_from
date (optional) Example: 2023-02-08

Only return folders that were edited past or at the specified date

modification_date_to
date (optional) Example: 2023-02-09

Only return folders that were edited before or at the specified date

include_hidden
boolean (optional) Default: false Example: false

Flag to include hidden folders

access_role
enum (optional) 

Only return folders that the user has access with a specific role. If not provided, all folders the user has access to will be returned.

Choices: ADMIN SUBGROUP_ADMIN OWNER USER

expand
string (optional) Example: owner

A comma separated list of related domain objects that should be expanded for all items returned

Choices: owner

limit
number (optional) Default: 20 

Maximum number of folders to return - Maximum allowed limit is 100

offset
number (optional) Default: 0 

Offset into result-set (useful for pagination)

Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
X-Total-Count: 1
X-Limit: 20
X-Offset: 0
Body
[
  {
    "id": "46123",
    "title": "Luke's Folder",
    "owner_id": "11038",
    "group_id": "1200",
    "parent_folder_id": "null",
    "hidden": false,
    "content_type": "PROJECTS",
    "creation_date": "2017-02-10T12:34:56.789+0200",
    "version_date": "2017-02-15T12:34:56.789+0200"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "the unique id of the folder"
      },
      "title": {
        "type": "string",
        "description": "the display name of the folder"
      },
      "owner_id": {
        "type": "string",
        "description": "the id of the folder owner"
      },
      "group_id": {
        "type": [
          "string",
          "null"
        ],
        "description": "the id of the group to which the folder is associated"
      },
      "parent_folder_id": {
        "type": [
          "string",
          "null"
        ],
        "description": "the id of the closest accessible parent folder in which the folder is located for the user. null is used folders which are not in a parent folder or don't have closest accessible parent folder"
      },
      "hidden": {
        "type": "boolean",
        "description": "indicating if the folder is hidden"
      },
      "content_type": {
        "type": "string",
        "enum": [
          "PROJECTS",
          "TEMPLATES"
        ],
        "default": "PROJECTS",
        "description": "indicates if this folder holds Projects or Templates"
      },
      "creation_date": {
        "type": "string",
        "description": "date when the folder was created"
      },
      "version_date": {
        "type": "string",
        "description": "date when the folder was last modified"
      }
    },
    "required": [
      "id",
      "title",
      "owner_id",
      "group_id",
      "parent_folder_id",
      "hidden",
      "content_type",
      "creation_date",
      "version_date"
    ]
  }
}

Create Folder
POST/folders

Create a folder. A folder may either contain projects or templates, as well as children folders of the same type. A private folder is intended for your use only, while a group folder may be shared with the members of that group.

Example URI

POST /api/v2/folders
Request  Create top-level Private Folder to hold Projects
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "Luke's Private Folder",
  "content_type": "PROJECTS"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the folder"
    },
    "content_type": {
      "type": "string",
      "enum": [
        "PROJECTS",
        "TEMPLATES"
      ],
      "default": "PROJECTS",
      "description": "indicate if the folder should hold Projects or Templates"
    }
  },
  "required": [
    "title"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /folders/46123
Body
{
  "id": "46123",
  "title": "Luke's Private Folder",
  "owner_id": "11038",
  "group_id": "null",
  "parent_folder_id": "null",
  "hidden": false,
  "content_type": "PROJECTS",
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the unique id of the folder"
    },
    "title": {
      "type": "string",
      "description": "the display name of the folder"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the folder owner"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "null is used for the private folders"
    },
    "parent_folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the closest accessible parent folder in which the folder is located for the user. null is used folders which are not in a parent folder or don't have closest accessible parent folder"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the folder is hidden"
    },
    "content_type": {
      "type": "string",
      "enum": [
        "PROJECTS",
        "TEMPLATES"
      ],
      "default": "PROJECTS",
      "description": "indicates if this folder holds Projects or Templates"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the folder was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the folder was last modified"
    }
  },
  "required": [
    "id",
    "title",
    "owner_id",
    "group_id",
    "parent_folder_id",
    "hidden",
    "content_type",
    "creation_date",
    "version_date"
  ]
}
Request  Create top-level Private Folder to hold Templates
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "Luke's Private Folder",
  "content_type": "TEMPLATES"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the folder"
    },
    "content_type": {
      "type": "string",
      "description": "indicate if the folder should hold Projects or Templates"
    }
  },
  "required": [
    "title"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /folders/46123
Body
{
  "id": "46123",
  "title": "Luke's Private Folder",
  "owner_id": "11038",
  "group_id": "null",
  "parent_folder_id": "null",
  "hidden": false,
  "content_type": "TEMPLATES",
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the unique id of the folder"
    },
    "title": {
      "type": "string",
      "description": "the display name of the folder"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the folder owner"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "null is used for the private folders"
    },
    "parent_folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the closest accessible parent folder in which the folder is located for the user. null is used folders which are not in a parent folder or don't have closest accessible parent folder"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the folder is hidden"
    },
    "content_type": {
      "type": "string",
      "description": "indicates if this folder holds Projects or Templates"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the folder was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the folder was last modified"
    }
  },
  "required": [
    "id",
    "title",
    "owner_id",
    "group_id",
    "parent_folder_id",
    "hidden",
    "content_type",
    "creation_date",
    "version_date"
  ]
}
Request  Create Private Folder as a Child of an Existing Private Folder
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "Luke's Private Folder",
  "content_type": "PROJECTS",
  "parent_folder_id": "36273"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the folder"
    },
    "content_type": {
      "type": "string",
      "enum": [
        "PROJECTS",
        "TEMPLATES"
      ],
      "default": "PROJECTS",
      "description": "indicate if the folder should hold Projects or Templates"
    },
    "parent_folder_id": {
      "type": "string"
    }
  },
  "required": [
    "title",
    "parent_folder_id"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /folders/46123
Body
{
  "id": "46123",
  "title": "Luke's Private Folder",
  "owner_id": "11038",
  "group_id": "null",
  "parent_folder_id": "36273",
  "hidden": false,
  "content_type": "PROJECTS",
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the unique id of the folder"
    },
    "title": {
      "type": "string",
      "description": "the display name of the folder"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the folder owner"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "null is used for the private folders"
    },
    "parent_folder_id": {
      "type": "string",
      "description": "the id of the closest accessible parent folder in which the folder is located for the user. null is used folders which are not in a parent folder or don't have closest accessible parent folder"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the folder is hidden"
    },
    "content_type": {
      "type": "string",
      "enum": [
        "PROJECTS",
        "TEMPLATES"
      ],
      "default": "PROJECTS",
      "description": "indicates if this folder holds Projects or Templates"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the folder was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the folder was last modified"
    }
  },
  "required": [
    "id",
    "title",
    "owner_id",
    "group_id",
    "parent_folder_id",
    "hidden",
    "content_type",
    "creation_date",
    "version_date"
  ]
}
Request  Create a top-level Group Folder to hold Projects
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "Group Folder",
  "content_type": "PROJECTS",
  "group_id": "1200"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the folder"
    },
    "content_type": {
      "type": "string",
      "enum": [
        "PROJECTS",
        "TEMPLATES"
      ],
      "default": "PROJECTS",
      "description": "indicate if the folder should hold Projects or Templates"
    },
    "group_id": {
      "type": "string",
      "description": "the id of the group to which the folder is associated"
    }
  },
  "required": [
    "title",
    "group_id"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /folders/46123
Body
{
  "id": "46123",
  "title": "Group Folder",
  "owner_id": "11038",
  "group_id": "1200",
  "parent_folder_id": "null",
  "hidden": false,
  "content_type": "PROJECTS",
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the unique id of the folder"
    },
    "title": {
      "type": "string",
      "description": "the display name of the folder"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the folder owner"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the group to which the folder is associated"
    },
    "parent_folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the closest accessible parent folder in which the folder is located for the user. null is used folders which are not in a parent folder or don't have closest accessible parent folder"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the folder is hidden"
    },
    "content_type": {
      "type": "string",
      "enum": [
        "PROJECTS",
        "TEMPLATES"
      ],
      "default": "PROJECTS",
      "description": "indicates if this folder holds Projects or Templates"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the folder was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the folder was last modified"
    }
  },
  "required": [
    "id",
    "title",
    "owner_id",
    "group_id",
    "parent_folder_id",
    "hidden",
    "content_type",
    "creation_date",
    "version_date"
  ]
}
Request  Create a top-level Group Folder to hold Templates
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "Group Folder",
  "content_type": "TEMPLATES",
  "group_id": "1200"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the folder"
    },
    "content_type": {
      "type": "string",
      "description": "indicate if the folder should hold Projects or Templates"
    },
    "group_id": {
      "type": "string",
      "description": "the id of the group to which the folder is associated"
    }
  },
  "required": [
    "title",
    "group_id"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /folders/46123
Body
{
  "id": "46123",
  "title": "Group Folder",
  "owner_id": "11038",
  "group_id": "1200",
  "parent_folder_id": "null",
  "hidden": false,
  "content_type": "TEMPLATES",
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the unique id of the folder"
    },
    "title": {
      "type": "string",
      "description": "the display name of the folder"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the folder owner"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the group to which the folder is associated"
    },
    "parent_folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the closest accessible parent folder in which the folder is located for the user. null is used folders which are not in a parent folder or don't have closest accessible parent folder"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the folder is hidden"
    },
    "content_type": {
      "type": "string",
      "description": "indicates if this folder holds Projects or Templates"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the folder was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the folder was last modified"
    }
  },
  "required": [
    "id",
    "title",
    "owner_id",
    "group_id",
    "parent_folder_id",
    "hidden",
    "content_type",
    "creation_date",
    "version_date"
  ]
}
Request  Create Group Folder as a Child of an Existing Group Folder
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "Group Folder",
  "content_type": "PROJECTS",
  "group_id": "1200",
  "parent_folder_id": "36274"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the folder"
    },
    "content_type": {
      "type": "string",
      "enum": [
        "PROJECTS",
        "TEMPLATES"
      ],
      "default": "PROJECTS",
      "description": "indicate if the folder should hold Projects or Templates"
    },
    "group_id": {
      "type": "string",
      "description": "the id of the group to which the folder is associated"
    },
    "parent_folder_id": {
      "type": "string"
    }
  },
  "required": [
    "title",
    "group_id",
    "parent_folder_id"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /projects/46123
Body
{
  "id": "46123",
  "title": "Group Folder",
  "owner_id": "11038",
  "group_id": "1200",
  "parent_folder_id": "36274",
  "hidden": false,
  "content_type": "PROJECTS",
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the unique id of the folder"
    },
    "title": {
      "type": "string",
      "description": "the display name of the folder"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the folder owner"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the group to which the folder is associated"
    },
    "parent_folder_id": {
      "type": "string",
      "description": "the id of the closest accessible parent folder in which the folder is located for the user. null is used folders which are not in a parent folder or don't have closest accessible parent folder"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the folder is hidden"
    },
    "content_type": {
      "type": "string",
      "enum": [
        "PROJECTS",
        "TEMPLATES"
      ],
      "default": "PROJECTS",
      "description": "indicates if this folder holds Projects or Templates"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the folder was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the folder was last modified"
    }
  },
  "required": [
    "id",
    "title",
    "owner_id",
    "group_id",
    "parent_folder_id",
    "hidden",
    "content_type",
    "creation_date",
    "version_date"
  ]
}

Update Folder
PATCH/folders/{id}

This endpoint complies with RFC 6902, the specification for JSON Patch. Please note that the ‘value’ of the patch operation should be the new owner membership id, not the new owner id.

  • Update a folder’s owner.

  • Update a folder’s parent folder given it’s id and return the modified objects.

  • Update a folder’s visibility, meaning hiding and unhiding folders which includes hiding everything beneath the folder.

The supported operations will grow in time.

Example URI

PATCH /api/v2/folders/36287
URI Parameters
HideShow
id
string (required) Example: 36287

the unique id of the folder

Request  Change Folder Owner
HideShow
Headers
Content-Type: application/json-patch+json
Body
[
  {
    "op": "replace",
    "path": "/owner_id",
    "value": "3128"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "op": {
        "type": "string",
        "enum": [
          "replace"
        ],
        "description": "The replace operation defined by RFC 6902"
      },
      "path": {
        "type": "string",
        "enum": [
          "/owner_id"
        ],
        "description": "JSON Pointer notation to the owner of the folder"
      },
      "value": {
        "type": "string",
        "description": "the unique identifier of the group membership of the new owner"
      }
    },
    "required": [
      "op",
      "path",
      "value"
    ]
  }
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": "46123",
  "title": "Luke's Folder",
  "owner_id": "11038",
  "group_id": "1200",
  "parent_folder_id": "null",
  "hidden": false,
  "content_type": "PROJECTS",
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the unique id of the folder"
    },
    "title": {
      "type": "string",
      "description": "the display name of the folder"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the folder owner"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the group to which the folder is associated"
    },
    "parent_folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the closest accessible parent folder in which the folder is located for the user. null is used folders which are not in a parent folder or don't have closest accessible parent folder"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the folder is hidden"
    },
    "content_type": {
      "type": "string",
      "enum": [
        "PROJECTS",
        "TEMPLATES"
      ],
      "default": "PROJECTS",
      "description": "indicates if this folder holds Projects or Templates"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the folder was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the folder was last modified"
    }
  },
  "required": [
    "id",
    "title",
    "owner_id",
    "group_id",
    "parent_folder_id",
    "hidden",
    "content_type",
    "creation_date",
    "version_date"
  ],
  "additionalProperties": false
}
Request  Move Folder to another folder
HideShow
Headers
Content-Type: application/json-patch+json
Body
[
  {
    "op": "replace",
    "path": "/folder_id",
    "value": "36284"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "op": {
        "type": "string",
        "enum": [
          "replace"
        ],
        "description": "The replace operation defined by RFC 6902"
      },
      "path": {
        "type": "string",
        "enum": [
          "/folder_id"
        ],
        "description": "JSON Pointer notation to the folder the mentioned folder will be moved into"
      },
      "value": {
        "type": "string",
        "description": "id of the new parent folder. In case of root folder, the value should be `0`."
      }
    },
    "required": [
      "op",
      "path",
      "value"
    ]
  }
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": "46123",
  "title": "Luke's Folder",
  "owner_id": "11038",
  "group_id": "1200",
  "parent_folder_id": "null",
  "hidden": false,
  "content_type": "PROJECTS",
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the unique id of the folder"
    },
    "title": {
      "type": "string",
      "description": "the display name of the folder"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the folder owner"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the group to which the folder is associated"
    },
    "parent_folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the closest accessible parent folder in which the folder is located for the user. null is used folders which are not in a parent folder or don't have closest accessible parent folder"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the folder is hidden"
    },
    "content_type": {
      "type": "string",
      "enum": [
        "PROJECTS",
        "TEMPLATES"
      ],
      "default": "PROJECTS",
      "description": "indicates if this folder holds Projects or Templates"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the folder was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the folder was last modified"
    }
  },
  "required": [
    "id",
    "title",
    "owner_id",
    "group_id",
    "parent_folder_id",
    "hidden",
    "content_type",
    "creation_date",
    "version_date"
  ],
  "additionalProperties": false
}
Request  Change Folder Visibility
HideShow
Headers
Content-Type: application/json-patch+json
Body
[
  {
    "op": "replace",
    "path": "/hidden",
    "value": false
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "op": {
        "type": "string",
        "enum": [
          "replace"
        ],
        "description": "The replace operation defined by RFC 6902"
      },
      "path": {
        "type": "string",
        "enum": [
          "/hidden"
        ],
        "description": "JSON Pointer notation to the whether the folder is hidden"
      },
      "value": {
        "type": "boolean",
        "description": "a boolean indicating whether the folder should be hidden"
      }
    },
    "required": [
      "op",
      "path",
      "value"
    ]
  }
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": "46123",
  "title": "Luke's Folder",
  "owner_id": "11038",
  "group_id": "1200",
  "parent_folder_id": "null",
  "hidden": false,
  "content_type": "PROJECTS",
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the unique id of the folder"
    },
    "title": {
      "type": "string",
      "description": "the display name of the folder"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the folder owner"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the group to which the folder is associated"
    },
    "parent_folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the closest accessible parent folder in which the folder is located for the user. null is used folders which are not in a parent folder or don't have closest accessible parent folder"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the folder is hidden"
    },
    "content_type": {
      "type": "string",
      "enum": [
        "PROJECTS",
        "TEMPLATES"
      ],
      "default": "PROJECTS",
      "description": "indicates if this folder holds Projects or Templates"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the folder was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the folder was last modified"
    }
  },
  "required": [
    "id",
    "title",
    "owner_id",
    "group_id",
    "parent_folder_id",
    "hidden",
    "content_type",
    "creation_date",
    "version_date"
  ],
  "additionalProperties": false
}

Update Folder Access
PUT/folders/{id}/access

Update the access settings of a folder.
A folder can be either shared with specific members, subgroups or with the whole group. Sharing it with subgroups or the group will automatically enable access for any new member joining these group structures. The folder owner is always added to the access settings membership IDs automatically, to guarantee that she has access at any time.

If the folder is located inside another folder, all access settings of the parent folder will cascade to the respective folder, even if you do not provide those within your request. This means the response might slightly differ from the request for this and other reasons mentioned above.

Example URI

PUT /api/v2/folders/36274/access
URI Parameters
HideShow
id
string (required) Example: 36274

id of the folder

Request  Update Folder Access
HideShow
Headers
Content-Type: application/json
Body
{
  "folder_id": "36274",
  "group_membership_ids": [
    "3127",
    "3129"
  ],
  "subgroup_ids": [
    "234"
  ],
  "full_group_access": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "folder_id": {
      "type": "string",
      "description": "id of the folder"
    },
    "group_membership_ids": {
      "type": "array",
      "items": [
        {
          "type": "string"
        },
        {
          "type": "string"
        }
      ],
      "description": "ids of memberships that have access to the folder granted"
    },
    "subgroup_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "ids of subgroups which members have access to the folder granted"
    },
    "full_group_access": {
      "type": "boolean",
      "description": "boolean flag indicating if all group members have access to the folder granted. if this has value 'true', it makes setting the id fields obsolete."
    }
  },
  "required": [
    "folder_id",
    "group_membership_ids",
    "subgroup_ids",
    "full_group_access"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "folder_id": "36274",
  "group_membership_ids": [
    "3127",
    "3129"
  ],
  "subgroup_ids": [
    "234"
  ],
  "full_group_access": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "folder_id": {
      "type": "string",
      "description": "id of the folder"
    },
    "group_membership_ids": {
      "type": "array",
      "items": [
        {
          "type": "string"
        },
        {
          "type": "string"
        }
      ],
      "description": "ids of memberships that have access to the folder granted"
    },
    "subgroup_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "ids of subgroups which members have access to the folder granted"
    },
    "full_group_access": {
      "type": "boolean",
      "description": "boolean flag indicating if all group members have access to the folder granted. if this has value 'true', it makes setting the id fields obsolete."
    }
  },
  "required": [
    "folder_id",
    "group_membership_ids",
    "subgroup_ids",
    "full_group_access"
  ],
  "additionalProperties": false
}

Delete Folder
DELETE/folders/{id}

Delete a folder

Example URI

DELETE /api/v2/folders/36288
URI Parameters
HideShow
id
string (required) Example: 36288

id of the folder

Response  204

Templates

The main functionality of a Template is to be copied as a new entry in the notebook. Templates are useful anytime you have a consistently repeated protocol or set of instructions. A template is intended to be like a starting point for a new entry so that monotonous and repetitive data need not be entered over and over when creating new entries.

Templates

Create Template
POST/templates

Create a Template

Example URI

POST /api/v2/templates
Request  Create Private Template
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "Luke's Private Template"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the template"
    }
  },
  "required": [
    "title"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /templates/53124
Body
{
  "title": "Luke's Private Template",
  "id": "36280",
  "owner_id": "11038",
  "entry_id": "548613",
  "group_id": "null",
  "folder_id": "null",
  "hidden": false,
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "collaborative": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the template"
    },
    "id": {
      "type": "string",
      "description": "the unique id of the template"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the template owner"
    },
    "entry_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the stable id of the entry which is stored inside the template"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the group to which the template is associated"
    },
    "folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the folder in which the template is stored"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the template is hidden"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the template was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the template was last modified"
    },
    "collaborative": {
      "type": "boolean",
      "description": "boolean flag indicating whether the template is collaborative. when true, the template can be edited by all members having access to the template. when false, the template is editable by its author only. its value is always false when the multi-author feature is disabled."
    }
  },
  "required": [
    "title",
    "id",
    "owner_id",
    "entry_id",
    "group_id",
    "folder_id",
    "hidden",
    "creation_date",
    "version_date",
    "collaborative"
  ]
}
Request  Create Private Template in a Folder
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "Luke's Private Template",
  "folder_id": "36282"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the template"
    },
    "folder_id": {
      "type": "string",
      "description": "the id of the folder in which the template is stored"
    }
  },
  "required": [
    "title",
    "folder_id"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /templates/53124
Body
{
  "title": "Luke's Private Template",
  "id": "36280",
  "owner_id": "11038",
  "entry_id": "548613",
  "group_id": "null",
  "folder_id": "36281",
  "hidden": false,
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "collaborative": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the template"
    },
    "id": {
      "type": "string",
      "description": "the unique id of the template"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the template owner"
    },
    "entry_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the stable id of the entry which is stored inside the template"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the group to which the template is associated"
    },
    "folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the folder in which the template is stored"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the template is hidden"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the template was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the template was last modified"
    },
    "collaborative": {
      "type": "boolean",
      "description": "boolean flag indicating whether the template is collaborative. when true, the template can be edited by all members having access to the template. when false, the template is editable by its author only. its value is always false when the multi-author feature is disabled."
    }
  },
  "required": [
    "title",
    "id",
    "owner_id",
    "entry_id",
    "group_id",
    "folder_id",
    "hidden",
    "creation_date",
    "version_date",
    "collaborative"
  ],
  "additionalProperties": false
}
Request  Create Group Template
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "Luke's Private Template",
  "group_id": "1200"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the template"
    },
    "group_id": {
      "type": "string",
      "description": "the id of the group to which the template is associated"
    }
  },
  "required": [
    "title",
    "group_id"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /templates/53124
Body
{
  "title": "Luke's Private Template",
  "id": "36280",
  "owner_id": "11038",
  "entry_id": "548613",
  "group_id": "1200",
  "folder_id": "null",
  "hidden": false,
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "collaborative": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the template"
    },
    "id": {
      "type": "string",
      "description": "the unique id of the template"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the template owner"
    },
    "entry_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the stable id of the entry which is stored inside the template"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the group to which the template is associated"
    },
    "folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the folder in which the template is stored"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the template is hidden"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the template was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the template was last modified"
    },
    "collaborative": {
      "type": "boolean",
      "description": "boolean flag indicating whether the template is collaborative. when true, the template can be edited by all members having access to the template. when false, the template is editable by its author only. its value is always false when the multi-author feature is disabled."
    }
  },
  "required": [
    "title",
    "id",
    "owner_id",
    "entry_id",
    "group_id",
    "folder_id",
    "hidden",
    "creation_date",
    "version_date",
    "collaborative"
  ],
  "additionalProperties": false
}
Request  Create Group Template in a Folder
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "Luke's Private Template",
  "folder_id": "36281",
  "group_id": "1200"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the template"
    },
    "folder_id": {
      "type": "string",
      "description": "the id of the folder in which the template is stored"
    },
    "group_id": {
      "type": "string",
      "description": "the id of the group to which the template is associated"
    }
  },
  "required": [
    "title",
    "folder_id",
    "group_id"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /templates/53124
Body
{
  "title": "Luke's Private Template",
  "id": "36280",
  "owner_id": "11038",
  "entry_id": "548613",
  "group_id": "1200",
  "folder_id": "36281",
  "hidden": false,
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "collaborative": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the template"
    },
    "id": {
      "type": "string",
      "description": "the unique id of the template"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the template owner"
    },
    "entry_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the stable id of the entry which is stored inside the template"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the group to which the template is associated"
    },
    "folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the folder in which the template is stored"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the template is hidden"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the template was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the template was last modified"
    },
    "collaborative": {
      "type": "boolean",
      "description": "boolean flag indicating whether the template is collaborative. when true, the template can be edited by all members having access to the template. when false, the template is editable by its author only. its value is always false when the multi-author feature is disabled."
    }
  },
  "required": [
    "title",
    "id",
    "owner_id",
    "entry_id",
    "group_id",
    "folder_id",
    "hidden",
    "creation_date",
    "version_date",
    "collaborative"
  ],
  "additionalProperties": false
}
Request  Create Template from an Existing Entry
HideShow

Creates a new template using the source entry identified in the Source-Id header. Note that the templates target group must be the same group as that of the source entry. Further, you must have read access to the source entry.

Headers
Content-Type: application/json
Source-Id: 938304
Body
{
  "title": "Luke's Private Template",
  "group_id": "1200"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the template"
    },
    "group_id": {
      "type": "string",
      "description": "The id of the group to which the template is associated. This has to be the same group ID as the one of the source entry"
    }
  },
  "required": [
    "title",
    "group_id"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /templates/53124
Body
{
  "title": "Luke's Private Template",
  "id": "36280",
  "owner_id": "11038",
  "entry_id": "548613",
  "group_id": "1200",
  "folder_id": "null",
  "hidden": false,
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "collaborative": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the template"
    },
    "id": {
      "type": "string",
      "description": "the unique id of the template"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the template owner"
    },
    "entry_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the stable id of the entry which is stored inside the template"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the group to which the template is associated"
    },
    "folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the folder in which the template is stored"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the template is hidden"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the template was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the template was last modified"
    },
    "collaborative": {
      "type": "boolean",
      "description": "boolean flag indicating whether the template is collaborative. when true, the template can be edited by all members having access to the template. when false, the template is editable by its author only. its value is always false when the multi-author feature is disabled."
    }
  },
  "required": [
    "title",
    "id",
    "owner_id",
    "entry_id",
    "group_id",
    "folder_id",
    "hidden",
    "creation_date",
    "version_date",
    "collaborative"
  ],
  "additionalProperties": false
}

List Templates
GET/templates{?group_ids,owner_ids,only_root_level,folder_id,template_ids,title,private_templates_only,creation_date_from,creation_date_to,modification_date_from,modification_date_to,include_hidden,access_role,expand,limit,offset}

Returns a list of templates the user has access to.

Example URI

GET /api/v2/templates?group_ids=1200,1201&owner_ids=11038,11039&only_root_level=true&folder_id=36274&template_ids=36279&title=My template&private_templates_only=true&creation_date_from=2023-02-08&creation_date_to=2023-02-09&modification_date_from=2023-02-08&modification_date_to=2023-02-09&include_hidden=false&access_role=&expand=&limit=&offset=
URI Parameters
HideShow
group_ids
string (optional) Example: 1200,1201

Only return templates that belong to the specified groups (comma separated list)

owner_ids
string (optional) Example: 11038,11039

Only return templates that are owned by the given users (comma separated list)

only_root_level
boolean (optional) Default: false Example: true

Only return root (top) level templates - I.e. templates that do not reside within a folder

folder_id
string (optional) Example: 36274

Only return templates that reside within the specified folder

template_ids
string (optional) Example: 36279

A comma separated list of template ids specifying the templates to be returned

title
string (optional) Example: My template

Only return templates with a title containing this string

private_templates_only
boolean (optional) Example: true

Only return the user’s private templates

creation_date_from
date (optional) Example: 2023-02-08

Only return templates that were created past or at the specified date

creation_date_to
date (optional) Example: 2023-02-09

Only return templates that were created before or at the specified date

modification_date_from
date (optional) Example: 2023-02-08

Only return templates that were edited past or at the specified date

modification_date_to
date (optional) Example: 2023-02-09

Only return templates that were edited before or at the specified date

include_hidden
boolean (optional) Default: false Example: false

Flag to include hidden templates

access_role
enum (optional) 

Only return templates that the user has access with a specific role. If not provided, all templates the user has access to will be returned.

Choices: ADMIN SUBGROUP_ADMIN OWNER USER

expand
string (optional) 

A comma separated list of related domain objects that should be expanded for all items returned

Choices: owner

limit
number (optional) Default: 20 

Maximum number of templates to return - Maximum allowed limit is 100

offset
number (optional) Default: 0 

Offset into result-set (useful for pagination)

Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
X-Total-Count: 1
X-Limit: 20
X-Offset: 0
Body
[
  {
    "title": "Luke's Private Template",
    "id": "36280",
    "owner_id": "11038",
    "entry_id": "548613",
    "group_id": "null",
    "folder_id": "null",
    "hidden": false,
    "creation_date": "2017-02-10T12:34:56.789+0200",
    "version_date": "2017-02-15T12:34:56.789+0200",
    "collaborative": false
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "description": "the display name of the template"
      },
      "id": {
        "type": "string",
        "description": "the unique id of the template"
      },
      "owner_id": {
        "type": "string",
        "description": "the id of the template owner"
      },
      "entry_id": {
        "type": [
          "string",
          "null"
        ],
        "description": "the stable id of the entry which is stored inside the template"
      },
      "group_id": {
        "type": [
          "string",
          "null"
        ],
        "description": "the id of the group to which the template is associated"
      },
      "folder_id": {
        "type": [
          "string",
          "null"
        ],
        "description": "the id of the folder in which the template is stored"
      },
      "hidden": {
        "type": "boolean",
        "description": "indicating if the template is hidden"
      },
      "creation_date": {
        "type": "string",
        "description": "date when the template was created"
      },
      "version_date": {
        "type": "string",
        "description": "date when the template was last modified"
      },
      "collaborative": {
        "type": "boolean",
        "description": "boolean flag indicating whether the template is collaborative. when true, the template can be edited by all members having access to the template. when false, the template is editable by its author only. its value is always false when the multi-author feature is disabled."
      }
    },
    "required": [
      "title",
      "id",
      "owner_id",
      "entry_id",
      "group_id",
      "folder_id",
      "hidden",
      "creation_date",
      "version_date",
      "collaborative"
    ]
  }
}

Get Template
GET/templates/{id}{?expand}

Returns the latest version of a template

Example URI

GET /api/v2/templates/36280?expand=
URI Parameters
HideShow
id
string (required) Example: 36280

id of the template

expand
string (optional) 

A comma separated list of related domain objects that should be expanded for the template returned

Choices: entry owner

Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "title": "Luke's Private Template",
  "id": "36280",
  "owner_id": "11038",
  "entry_id": "548613",
  "group_id": "null",
  "folder_id": "null",
  "hidden": false,
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "collaborative": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the template"
    },
    "id": {
      "type": "string",
      "description": "the unique id of the template"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the template owner"
    },
    "entry_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the stable id of the entry which is stored inside the template"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the group to which the template is associated"
    },
    "folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the folder in which the template is stored"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the template is hidden"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the template was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the template was last modified"
    },
    "collaborative": {
      "type": "boolean",
      "description": "boolean flag indicating whether the template is collaborative. when true, the template can be edited by all members having access to the template. when false, the template is editable by its author only. its value is always false when the multi-author feature is disabled."
    }
  },
  "required": [
    "title",
    "id",
    "owner_id",
    "entry_id",
    "group_id",
    "folder_id",
    "hidden",
    "creation_date",
    "version_date",
    "collaborative"
  ],
  "additionalProperties": false
}
Request  ?expand=entry
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "title": "Luke's Private Template",
  "id": "36280",
  "owner_id": "11038",
  "entry_id": "548613",
  "group_id": "null",
  "folder_id": "null",
  "hidden": false,
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "collaborative": false,
  "entry": {
    "id": "548613",
    "version_id": "5309878",
    "author_id": "11038",
    "creation_date": "2017-02-10T12:34:56.789+0200",
    "version_date": "2017-02-15T12:34:56.789+0200",
    "element_layout": {
      "grid_layout": true,
      "rows": [
        {
          "cells": [
            {
              "element_version_id": "2309983",
              "width": 60,
              "height": 40,
              "top": 0,
              "left": 0
            }
          ]
        }
      ]
    },
    "elements": [
      {
        "id": "e79cfbb5d2cb5a39b7a821a3ae0476e6605adcc2",
        "version_id": "2309983",
        "type": "TEXT"
      }
    ],
    "tags": [
      "luke",
      "star wars"
    ],
    "custom_dates": [
      {
        "name": "validation date",
        "value": "2017-12-25"
      }
    ],
    "template_id": "36280"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the template"
    },
    "id": {
      "type": "string",
      "description": "the unique id of the template"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the template owner"
    },
    "entry_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the stable id of the entry which is stored inside the template"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the group to which the template is associated"
    },
    "folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the folder in which the template is stored"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the template is hidden"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the template was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the template was last modified"
    },
    "collaborative": {
      "type": "boolean",
      "description": "boolean flag indicating whether the template is collaborative. when true, the template can be edited by all members having access to the template. when false, the template is editable by its author only. its value is always false when the multi-author feature is disabled."
    },
    "entry": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "the unique id of the entry"
        },
        "version_id": {
          "type": "string",
          "description": "the unique id of the entry"
        },
        "author_id": {
          "type": "string",
          "description": "the unique id of the user created the entry"
        },
        "creation_date": {
          "type": "string",
          "description": "date when the entry was created"
        },
        "version_date": {
          "type": "string",
          "description": "date when this entry was last modified"
        },
        "element_layout": {
          "type": "object",
          "properties": {
            "grid_layout": {
              "type": "boolean",
              "description": "indicates if the row is a grid layout or not"
            },
            "rows": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "object",
                "properties": {
                  "cells": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "object",
                      "properties": {
                        "element_version_id": {
                          "type": "string",
                          "description": "The version id of this element"
                        },
                        "width": {
                          "type": "number",
                          "description": "The number of cells this element spans horizontally, can be 1 to 12"
                        },
                        "height": {
                          "type": "number",
                          "description": "The number of cells this element spans vertically, can be 1 minimum"
                        },
                        "top": {
                          "type": "number",
                          "description": "The top vertical position of the cell, can be 0 minimum"
                        },
                        "left": {
                          "type": "number",
                          "description": "The left horizontal position of the cell, can be 0 to 11"
                        }
                      },
                      "required": [
                        "element_version_id",
                        "width",
                        "height",
                        "top",
                        "left"
                      ]
                    }
                  }
                },
                "required": [
                  "cells"
                ]
              },
              "description": "the notebook row/column layout of elements in the entry"
            }
          },
          "required": [
            "grid_layout",
            "rows"
          ],
          "description": "The layout of the elements in this entry"
        },
        "elements": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "The stable id of the element"
              },
              "version_id": {
                "type": "string",
                "description": "The version id of this element"
              },
              "type": {
                "type": "string",
                "enum": [
                  "DATA",
                  "FILE",
                  "IMAGE",
                  "TABLE",
                  "TEXT",
                  "WELL_PLATE",
                  "CHEMICAL_STRUCTURE"
                ],
                "description": "The type of the element"
              }
            },
            "required": [
              "id",
              "version_id",
              "type"
            ]
          },
          "description": "The elements in this entry"
        },
        "tags": {
          "type": "array",
          "items": [
            {
              "type": "string"
            },
            {
              "type": "string"
            }
          ],
          "description": "The tags for this entry. Tags are case insensitive."
        },
        "custom_dates": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "The name of the custom date. Names are case insensitive."
              },
              "value": {
                "type": "string",
                "description": "The value of this custom date"
              }
            },
            "required": [
              "name",
              "value"
            ]
          },
          "description": "Custom dates for this entry"
        },
        "template_id": {
          "type": "string",
          "description": "template location of the entry"
        }
      },
      "required": [
        "id",
        "version_id",
        "author_id",
        "creation_date",
        "version_date",
        "element_layout",
        "elements",
        "tags",
        "custom_dates",
        "template_id"
      ],
      "description": "the entry referenced by the `entry_id` property"
    }
  },
  "required": [
    "title",
    "id",
    "owner_id",
    "entry_id",
    "group_id",
    "folder_id",
    "hidden",
    "creation_date",
    "version_date",
    "collaborative",
    "entry"
  ],
  "additionalProperties": false
}

Update Template
PATCH/templates/{id}

This endpoint complies with RFC 6902, the specification for JSON Patch.

  • Update a template’s owner.

  • Update a template parent folder given it’s id and return the modified objects.

  • Update a template’s visibility, meaning hiding and unhiding templates.

The supported operations will grow in time.

Example URI

PATCH /api/v2/templates/36280
URI Parameters
HideShow
id
string (required) Example: 36280

the unique id of the template

Request  Change Template Owner
HideShow

Please note, to change the owner of a template you must send the group membership id of the new owner (not the user id!).

Headers
Content-Type: application/json-patch+json
Body
[
  {
    "op": "replace",
    "path": "/owner_id",
    "value": "3130"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "op": {
        "type": "string",
        "enum": [
          "replace"
        ],
        "description": "The replace operation defined by RFC 6902"
      },
      "path": {
        "type": "string",
        "enum": [
          "/owner_id"
        ],
        "description": "JSON Pointer notation to the owner of the project"
      },
      "value": {
        "type": "string",
        "description": "the unique identifier of the group membership of the new owner"
      }
    },
    "required": [
      "op",
      "path",
      "value"
    ]
  }
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "title": "Luke's Private Template",
  "id": "36280",
  "owner_id": "11038",
  "entry_id": "548613",
  "group_id": "null",
  "folder_id": "null",
  "hidden": false,
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "collaborative": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the template"
    },
    "id": {
      "type": "string",
      "description": "the unique id of the template"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the template owner"
    },
    "entry_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the stable id of the entry which is stored inside the template"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the group to which the template is associated"
    },
    "folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the folder in which the template is stored"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the template is hidden"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the template was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the template was last modified"
    },
    "collaborative": {
      "type": "boolean",
      "description": "boolean flag indicating whether the template is collaborative. when true, the template can be edited by all members having access to the template. when false, the template is editable by its author only. its value is always false when the multi-author feature is disabled."
    }
  },
  "required": [
    "title",
    "id",
    "owner_id",
    "entry_id",
    "group_id",
    "folder_id",
    "hidden",
    "creation_date",
    "version_date",
    "collaborative"
  ],
  "additionalProperties": false
}
Request  Move Template to another folder
HideShow
Headers
Content-Type: application/json-patch+json
Body
[
  {
    "op": "replace",
    "path": "/folder_id",
    "value": "36281"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "op": {
        "type": "string",
        "enum": [
          "replace"
        ],
        "description": "The replace operation defined by RFC 6902"
      },
      "path": {
        "type": "string",
        "enum": [
          "/folder_id"
        ],
        "description": "JSON Pointer notation to the folder the mentioned template will be moved into"
      },
      "value": {
        "type": "string",
        "description": "id of the new parent folder. In case of root folder, the value should be `0`."
      }
    },
    "required": [
      "op",
      "path",
      "value"
    ]
  }
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "title": "Luke's Private Template",
  "id": "36280",
  "owner_id": "11038",
  "entry_id": "548613",
  "group_id": "null",
  "folder_id": "null",
  "hidden": false,
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "collaborative": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the template"
    },
    "id": {
      "type": "string",
      "description": "the unique id of the template"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the template owner"
    },
    "entry_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the stable id of the entry which is stored inside the template"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the group to which the template is associated"
    },
    "folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the folder in which the template is stored"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the template is hidden"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the template was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the template was last modified"
    },
    "collaborative": {
      "type": "boolean",
      "description": "boolean flag indicating whether the template is collaborative. when true, the template can be edited by all members having access to the template. when false, the template is editable by its author only. its value is always false when the multi-author feature is disabled."
    }
  },
  "required": [
    "title",
    "id",
    "owner_id",
    "entry_id",
    "group_id",
    "folder_id",
    "hidden",
    "creation_date",
    "version_date",
    "collaborative"
  ],
  "additionalProperties": false
}
Request  Change Template Visibility
HideShow
Headers
Content-Type: application/json-patch+json
Body
[
  {
    "op": "replace",
    "path": "/hidden",
    "value": false
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "op": {
        "type": "string",
        "enum": [
          "replace"
        ],
        "description": "The replace operation defined by RFC 6902"
      },
      "path": {
        "type": "string",
        "enum": [
          "/hidden"
        ],
        "description": "JSON Pointer notation to the whether the template is hidden"
      },
      "value": {
        "type": "boolean",
        "description": "a boolean indicating whether the template should be hidden"
      }
    },
    "required": [
      "op",
      "path",
      "value"
    ]
  }
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "title": "Luke's Private Template",
  "id": "36280",
  "owner_id": "11038",
  "entry_id": "548613",
  "group_id": "null",
  "folder_id": "null",
  "hidden": false,
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "collaborative": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "the display name of the template"
    },
    "id": {
      "type": "string",
      "description": "the unique id of the template"
    },
    "owner_id": {
      "type": "string",
      "description": "the id of the template owner"
    },
    "entry_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the stable id of the entry which is stored inside the template"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the group to which the template is associated"
    },
    "folder_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "the id of the folder in which the template is stored"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicating if the template is hidden"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the template was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when the template was last modified"
    },
    "collaborative": {
      "type": "boolean",
      "description": "boolean flag indicating whether the template is collaborative. when true, the template can be edited by all members having access to the template. when false, the template is editable by its author only. its value is always false when the multi-author feature is disabled."
    }
  },
  "required": [
    "title",
    "id",
    "owner_id",
    "entry_id",
    "group_id",
    "folder_id",
    "hidden",
    "creation_date",
    "version_date",
    "collaborative"
  ],
  "additionalProperties": false
}

Update Template Access
PUT/templates/{id}/access

Update the access settings of a template.
A template can be either shared with specific members, subgroups or with the whole group. Sharing it with subgroups or the group will automatically enable access for any new member joining these group structures. The template owner is always added to the access settings membership IDs automatically, to guarantee that she has access at any time.

If the template is located in a folder, all access settings of that folder will cascade to the respective template, even if you do not provide those within your request. This means the response might slightly differ from the request for this and other reasons mentioned above.

Example URI

PUT /api/v2/templates/36280/access
URI Parameters
HideShow
id
string (required) Example: 36280

id of the template

Request  Update Template Access
HideShow
Headers
Content-Type: application/json
Body
{
  "template_id": "36280",
  "group_membership_ids": [
    "3127",
    "3129"
  ],
  "subgroup_ids": [
    "234"
  ],
  "full_group_access": false,
  "collaborative": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "template_id": {
      "type": "string",
      "description": "id of the template"
    },
    "group_membership_ids": {
      "type": "array",
      "items": [
        {
          "type": "string"
        },
        {
          "type": "string"
        }
      ],
      "description": "ids of memberships that have access to the template granted"
    },
    "subgroup_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "ids of subgroups which members have access to the template granted"
    },
    "full_group_access": {
      "type": "boolean",
      "description": "boolean flag indicating if all group members have access to the template granted. if this has value 'true', it makes setting the id fields obsolete."
    },
    "collaborative": {
      "type": "boolean",
      "description": "boolean flag indicating whether the template should be collaborative. when true, the template can be edited by all members having access to the template. when false, the template is editable by its author only. its default value is false. making a template collaborative is only possible when the multi-author feature is enabled. its value is always false when the feature is disabled."
    }
  },
  "required": [
    "template_id",
    "group_membership_ids",
    "subgroup_ids",
    "full_group_access"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "template_id": "36280",
  "group_membership_ids": [
    "3127",
    "3129"
  ],
  "subgroup_ids": [
    "234"
  ],
  "full_group_access": false,
  "collaborative": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "template_id": {
      "type": "string",
      "description": "id of the template"
    },
    "group_membership_ids": {
      "type": "array",
      "items": [
        {
          "type": "string"
        },
        {
          "type": "string"
        }
      ],
      "description": "ids of memberships that have access to the template granted"
    },
    "subgroup_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "ids of subgroups which members have access to the template granted"
    },
    "full_group_access": {
      "type": "boolean",
      "description": "boolean flag indicating if all group members have access to the template granted. if this has value 'true', it makes setting the id fields obsolete."
    },
    "collaborative": {
      "type": "boolean",
      "description": "boolean flag indicating whether the template should be collaborative. when true, the template can be edited by all members having access to the template. when false, the template is editable by its author only. its default value is false. making a template collaborative is only possible when the multi-author feature is enabled. its value is always false when the feature is disabled."
    }
  },
  "required": [
    "template_id",
    "group_membership_ids",
    "subgroup_ids",
    "full_group_access"
  ],
  "additionalProperties": false
}

Delete Template
DELETE/templates/{id}

Delete a template

Example URI

DELETE /api/v2/templates/36285
URI Parameters
HideShow
id
string (required) Example: 36285

id of the template

Response  204

Template Filters

List Template Filters
GET/template-filters{?group_id,title,include_hidden,folder_id,search_by_ids,limit,offset}

[beta] Returns a list of Template and Template Folders that the user has access to. When both folder_id and title are provided, the response will include only values matching both requirements. The response object will include a path field when the request includes the search_by_ids or title parameter.

Example URI

GET /api/v2/template-filters?group_id=1200&title=My template&include_hidden=false&folder_id=36274&search_by_ids=36274,36288&limit=&offset=
URI Parameters
HideShow
group_id
string (required) Example: 1200

Only return templates/folders that belong to the specified group.

folder_id
string (optional) Example: 36274

Only return templates/folders that reside within the specified folder. Returns the root folder if the parameter is set to 0.

search_by_ids
string (optional) Example: 36274,36288

A comma separated list of one or more template/folder ids. If provided, the response will include Template ids matching these specific ids. Note that this parameter cannot be used in conjunction with the title parameter.

title
string (optional) Example: My template

Only return templates/folders with a title containing this string. Note that this parameter cannot be used in conjunction with the search_by_ids parameter.

include_hidden
boolean (optional) Default: false Example: false

Flag to include hidden templates/folders

limit
number (optional) Default: 20 

Maximum number of templates/folders to return

offset
number (optional) Default: 0 

Offset into result-set (useful for pagination)

Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
X-Total-Count: 1
X-Limit: 20
X-Offset: 0
Body
[
  {
    "id": "46123",
    "title": "Luke's Private Project",
    "is_folder": false,
    "path": [
      "46121",
      "46122"
    ],
    "number_of_projects": 1
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "the unique id of the project/folder"
      },
      "title": {
        "type": "string",
        "description": "the display name of the project"
      },
      "is_folder": {
        "type": "boolean",
        "description": "indicating if the entity is a folder"
      },
      "path": {
        "type": [
          "array",
          "null"
        ],
        "items": [
          {
            "type": "string"
          },
          {
            "type": "string"
          }
        ],
        "description": "an ordered list of folder ids that lead to this project or folder"
      },
      "number_of_projects": {
        "type": [
          "number",
          "null"
        ],
        "description": "the total number of projects in the folder (and its subfolders)"
      }
    },
    "required": [
      "id",
      "title",
      "is_folder"
    ]
  }
}

Notebook Entries

An Entry is the central piece of the notebook. Entries represent a single item in the notebook. Each entry consists of multiple entry elements of different types and can also have metadata associated with it. Examples for metadata are tags and custom dates. Each entry belongs to a project and has a title. These are the only mandatory fields.

All operations on entries are automatically versioned.

The following operations are available for entries:

Entries

List Entries
GET/entries{?sort,omit_empty_title,title,expand,limit,offset,group_ids,project_ids,folder_ids,author_ids,subgroup_ids,co_author_ids,co_author_subgroup_ids,tag_ids,favorites,creation_date_from,creation_date_to,modification_date_from,modification_date_to,custom_date_ids,skip_total_count,siwor_statuses,sw_statuses,include_hidden}

Returns the list of entries. See also Entry Filters to retrieve aggregate data about entries.

Example URI

GET /api/v2/entries?sort=&omit_empty_title=&title=&expand=&limit=&offset=&group_ids=&project_ids=&folder_ids=&author_ids=&subgroup_ids=&co_author_ids=&co_author_subgroup_ids=&tag_ids=&favorites=&creation_date_from=2024-01-10&creation_date_to=2024-01-12&modification_date_from=2024-01-14&modification_date_to=2024-01-16&custom_date_ids=&skip_total_count=&siwor_statuses=&sw_statuses=&include_hidden=false
URI Parameters
HideShow
sort
string (optional) 

Field to sort the results by. When omitted results are sorted by user application settings

Choices: title -title creation_date -creation_date modification_date -modification_date

omit_empty_title
boolean (optional) Default: false 

Omit entries without a title in the result set

title
string (optional) 

Partial string to match the entry title

limit
number (optional) Default: 20 

Maximum number of projects to return. The maximum for limit is 50 items.

offset
number (optional) Default: 0 

Offset into result-set (useful for pagination)

expand
string (optional) 

A comma separated list of related domain objects that should be expanded for all items returned.

Choices: author project last_editor

group_ids
string (optional) 

A comma separated list of group ids that results in returning only entries within the specified group(s)

project_ids
string (optional) 

A comma separated list of project ids that results in returning only entries within the specified project(s)

folder_ids
string (optional) 

[beta] A comma separated list of folder ids that results in returning only entries residing under the specified folder(s). Please note that this param is in beta and may be subject to change.

author_ids
string (optional) 

A comma separated list of author ids that results in returning only entries owned by the specified author(s)

subgroup_ids
string (optional) 

[beta] A comma separated list of subgroup ids that results in returning only entries by the author(s) in the specified subgroup(s). This filter is applicable only when a single group id is passed as a parameter. Please note that this param is in beta and may be subject to change.

co_author_ids
string (optional) 

[beta] A comma separated list of co-author ids that results in returning only entries contributed by the specified co-author(s). Please note that this param is in beta and may be subject to change.

co_author_subgroup_ids
string (optional) 

[beta] A comma separated list of subgroup ids that results in returning only entries contributed by the co-author(s) in the specified subgroup(s). This filter is applicable only when a single group id is passed as a parameter. Please note that this param is in beta and may be subject to change.

tag_ids
string (optional) 

A comma separated list of tag ids that results in returning only entries has the specified tag(s)

favorites
boolean (optional) Default: false 

Field to return only the entries marked as favorites

creation_date_from
date (optional) Example: 2024-01-10

Field to return only the entries that were created past or at the specified date

creation_date_to
date (optional) Example: 2024-01-12

Field to return only the entries that were created before or at the specified date

modification_date_from
date (optional) Example: 2024-01-14

Field to return only the entries that were edited past or at the specified date

modification_date_to
date (optional) Example: 2024-01-16

Field to return only the entries that were edited before or at the specified date

custom_date_ids
string (optional) 

A comma separated list of custom date ids that results in returning only entries has the specified custom date(s)

skip_total_count
boolean (optional) Default: false 

Field to skip the calculation of the total number of entries that match the query

siwor_statuses
string (optional) 

[beta] A comma separated list of list of statuses to return only the entries with the specified Signature Workflows statuses. Please note that this param is in beta and may be subject to change.

  • NOT_STARTED,

  • UNDER_REVIEW,

  • REVIEW_COMPLETED,

  • REJECTED

sw_statuses
string (optional) 

[beta] A comma separated list of list of statuses to return only the entries with the specified Sign and Witness statuses. Please note that this param is in beta and may be subject to change.

  • NOT_SIGNED

  • SIGNED_BY_OWNER

  • WITNESSED

include_hidden
boolean (optional) Default: false Example: false

[beta] Flag to include hidden entries

Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
X-Total-Count: 1
X-Limit: 20
X-Offset: 0
Body
[
  {
    "id": "2309878",
    "version_id": "5309878",
    "author_id": "11038",
    "creation_date": "2017-02-10T12:34:56.789+0200",
    "version_date": "2017-02-15T12:34:56.789+0200",
    "element_layout": {
      "grid_layout": true,
      "rows": [
        {
          "cells": [
            {
              "element_version_id": "2309983",
              "width": 60,
              "height": 40,
              "top": 0,
              "left": 0
            }
          ]
        }
      ]
    },
    "elements": [
      {
        "id": "e79cfbb5d2cb5a39b7a821a3ae0476e6605adcc2",
        "version_id": "2309983",
        "type": "DATA"
      }
    ],
    "tags": [
      "luke",
      "star wars"
    ],
    "custom_dates": [
      {
        "name": "validation date",
        "value": "2017-12-25"
      }
    ],
    "project_id": "36272",
    "title": "Luke's Private Entry",
    "entry_number": 1,
    "hidden": false,
    "editable": true,
    "last_editor_id": "11038",
    "author": {
      "id": "11038",
      "email": "luke.skywalker@starwars.com",
      "deactivated": false,
      "first_name": "Luke",
      "last_name": "Skywalker",
      "profile_picture_hash": "bhOwHTKEjrPTDeiMtTnc",
      "iam_id": "d229cc70-455d-421d-9938-b2d8b4dee79e"
    }
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "the stable pointer to the most current version `blockId`"
      },
      "version_id": {
        "type": "string",
        "description": "the unique id of the entry"
      },
      "author_id": {
        "type": "string",
        "description": "the unique id of the user created the entry"
      },
      "creation_date": {
        "type": "string",
        "description": "date when the entry was created"
      },
      "version_date": {
        "type": "string",
        "description": "date when this entry was last modified"
      },
      "element_layout": {
        "type": "object",
        "properties": {
          "grid_layout": {
            "type": "boolean",
            "description": "indicates if the row is a grid layout or not"
          },
          "rows": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "object",
              "properties": {
                "cells": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "properties": {
                      "element_version_id": {
                        "type": "string",
                        "description": "The version id of this element"
                      },
                      "width": {
                        "type": "number",
                        "description": "The number of cells this element spans horizontally, can be 1 to 12"
                      },
                      "height": {
                        "type": "number",
                        "description": "The number of cells this element spans vertically, can be 1 minimum"
                      },
                      "top": {
                        "type": "number",
                        "description": "The top vertical position of the cell, can be 0 minimum"
                      },
                      "left": {
                        "type": "number",
                        "description": "The left horizontal position of the cell, can be 0 to 11"
                      }
                    },
                    "required": [
                      "element_version_id",
                      "width",
                      "height",
                      "top",
                      "left"
                    ]
                  }
                }
              },
              "required": [
                "cells"
              ]
            },
            "description": "the notebook row/column layout of elements in the entry"
          }
        },
        "required": [
          "grid_layout",
          "rows"
        ],
        "description": "The layout of the elements in this entry"
      },
      "elements": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "The stable id of the element"
            },
            "version_id": {
              "type": "string",
              "description": "The version id of this element"
            },
            "type": {
              "type": "string",
              "enum": [
                "DATA",
                "FILE",
                "IMAGE",
                "TABLE",
                "TEXT",
                "WELL_PLATE",
                "CHEMICAL_STRUCTURE"
              ],
              "description": "The type of the element"
            }
          },
          "required": [
            "id",
            "version_id",
            "type"
          ]
        },
        "description": "The elements in this entry"
      },
      "tags": {
        "type": "array",
        "items": [
          {
            "type": "string"
          },
          {
            "type": "string"
          }
        ],
        "description": "The tags for this entry. Tags are case insensitive."
      },
      "custom_dates": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "The name of the custom date. Names are case insensitive."
            },
            "value": {
              "type": "string",
              "description": "The value of this custom date"
            }
          },
          "required": [
            "name",
            "value"
          ]
        },
        "description": "Custom dates for this entry"
      },
      "project_id": {
        "type": "string",
        "description": "project location of the entry"
      },
      "title": {
        "type": "string",
        "description": "the display name of the entry"
      },
      "entry_number": {
        "type": "number",
        "description": "position of the entry inside the project"
      },
      "hidden": {
        "type": "boolean",
        "description": "indicates if the entry is hidden or visible"
      },
      "editable": {
        "type": "boolean",
        "description": "Indicates if the requesting user has write access to the entry. An entry is editable if the user is the entry author while the entry is neither signed nor hidden."
      },
      "last_editor_id": {
        "type": "string",
        "description": "the unique id of the last user who made a modification to the entry"
      },
      "author": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "id of the user"
          },
          "email": {
            "type": "string",
            "description": "email of the user"
          },
          "deactivated": {
            "type": "boolean",
            "description": "the flags shows if the user's account is deactivated"
          },
          "first_name": {
            "type": "string",
            "description": "first name of the user"
          },
          "last_name": {
            "type": "string",
            "description": "last name of the user"
          },
          "profile_picture_hash": {
            "type": [
              "string",
              "null"
            ],
            "description": "a hash to be used for the profile picture location url"
          },
          "iam_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "user uuid identifying the user in IAM"
          }
        },
        "required": [
          "id",
          "email",
          "deactivated",
          "first_name",
          "last_name",
          "profile_picture_hash",
          "iam_id"
        ],
        "additionalProperties": false,
        "description": "the user who created the entry"
      }
    },
    "required": [
      "id",
      "version_id",
      "author_id",
      "creation_date",
      "version_date",
      "element_layout",
      "elements",
      "tags",
      "custom_dates",
      "project_id",
      "title",
      "entry_number",
      "hidden",
      "editable",
      "last_editor_id"
    ]
  }
}

Get Entry
GET/entries/{id}{?expand}

Returns the entry with the given id

Example URI

GET /api/v2/entries/938302?expand=
URI Parameters
HideShow
id
string (required) Example: 938302

id of the entry

expand
string (optional) 

A comma separated list of related domain objects that should be expanded for the item returned.

Choices: author project last_editor

Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": "2309878",
  "version_id": "5309878",
  "author_id": "11038",
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "element_layout": {
    "grid_layout": true,
    "rows": [
      {
        "cells": [
          {
            "element_version_id": "2309983",
            "width": 60,
            "height": 40,
            "top": 0,
            "left": 0
          }
        ]
      }
    ]
  },
  "elements": [
    {
      "id": "e79cfbb5d2cb5a39b7a821a3ae0476e6605adcc2",
      "version_id": "2309983",
      "type": "DATA"
    }
  ],
  "tags": [
    "luke",
    "star wars"
  ],
  "custom_dates": [
    {
      "name": "validation date",
      "value": "2017-12-25"
    }
  ],
  "project_id": "36272",
  "title": "Luke's Private Entry",
  "entry_number": 1,
  "hidden": false,
  "editable": true,
  "last_editor_id": "11038",
  "author": {
    "id": "11038",
    "email": "luke.skywalker@starwars.com",
    "deactivated": false,
    "first_name": "Luke",
    "last_name": "Skywalker",
    "profile_picture_hash": "bhOwHTKEjrPTDeiMtTnc",
    "iam_id": "d229cc70-455d-421d-9938-b2d8b4dee79e"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the stable pointer to the most current version `blockId`"
    },
    "version_id": {
      "type": "string",
      "description": "the unique id of the entry"
    },
    "author_id": {
      "type": "string",
      "description": "the unique id of the user created the entry"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the entry was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when this entry was last modified"
    },
    "element_layout": {
      "type": "object",
      "properties": {
        "grid_layout": {
          "type": "boolean",
          "description": "indicates if the row is a grid layout or not"
        },
        "rows": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "object",
            "properties": {
              "cells": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "properties": {
                    "element_version_id": {
                      "type": "string",
                      "description": "The version id of this element"
                    },
                    "width": {
                      "type": "number",
                      "description": "The number of cells this element spans horizontally, can be 1 to 12"
                    },
                    "height": {
                      "type": "number",
                      "description": "The number of cells this element spans vertically, can be 1 minimum"
                    },
                    "top": {
                      "type": "number",
                      "description": "The top vertical position of the cell, can be 0 minimum"
                    },
                    "left": {
                      "type": "number",
                      "description": "The left horizontal position of the cell, can be 0 to 11"
                    }
                  },
                  "required": [
                    "element_version_id",
                    "width",
                    "height",
                    "top",
                    "left"
                  ]
                }
              }
            },
            "required": [
              "cells"
            ]
          },
          "description": "the notebook row/column layout of elements in the entry"
        }
      },
      "required": [
        "grid_layout",
        "rows"
      ],
      "description": "The layout of the elements in this entry"
    },
    "elements": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The stable id of the element"
          },
          "version_id": {
            "type": "string",
            "description": "The version id of this element"
          },
          "type": {
            "type": "string",
            "enum": [
              "DATA",
              "FILE",
              "IMAGE",
              "TABLE",
              "TEXT",
              "WELL_PLATE",
              "CHEMICAL_STRUCTURE"
            ],
            "description": "The type of the element"
          }
        },
        "required": [
          "id",
          "version_id",
          "type"
        ]
      },
      "description": "The elements in this entry"
    },
    "tags": {
      "type": "array",
      "items": [
        {
          "type": "string"
        },
        {
          "type": "string"
        }
      ],
      "description": "The tags for this entry. Tags are case insensitive."
    },
    "custom_dates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of the custom date. Names are case insensitive."
          },
          "value": {
            "type": "string",
            "description": "The value of this custom date"
          }
        },
        "required": [
          "name",
          "value"
        ]
      },
      "description": "Custom dates for this entry"
    },
    "project_id": {
      "type": "string",
      "description": "project location of the entry"
    },
    "title": {
      "type": "string",
      "description": "the display name of the entry"
    },
    "entry_number": {
      "type": "number",
      "description": "position of the entry inside the project"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicates if the entry is hidden or visible"
    },
    "editable": {
      "type": "boolean",
      "description": "Indicates if the requesting user has write access to the entry. An entry is editable if the user is the entry author while the entry is neither signed nor hidden."
    },
    "last_editor_id": {
      "type": "string",
      "description": "the unique id of the last user who made a modification to the entry"
    },
    "author": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "id of the user"
        },
        "email": {
          "type": "string",
          "description": "email of the user"
        },
        "deactivated": {
          "type": "boolean",
          "description": "the flags shows if the user's account is deactivated"
        },
        "first_name": {
          "type": "string",
          "description": "first name of the user"
        },
        "last_name": {
          "type": "string",
          "description": "last name of the user"
        },
        "profile_picture_hash": {
          "type": [
            "string",
            "null"
          ],
          "description": "a hash to be used for the profile picture location url"
        },
        "iam_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "user uuid identifying the user in IAM"
        }
      },
      "required": [
        "id",
        "email",
        "deactivated",
        "first_name",
        "last_name",
        "profile_picture_hash",
        "iam_id"
      ],
      "additionalProperties": false,
      "description": "the user who created the entry"
    }
  },
  "required": [
    "id",
    "version_id",
    "author_id",
    "creation_date",
    "version_date",
    "element_layout",
    "elements",
    "tags",
    "custom_dates",
    "project_id",
    "title",
    "entry_number",
    "hidden",
    "editable",
    "last_editor_id"
  ],
  "additionalProperties": false
}

Create Entry
POST/entries

Create a entry

Example URI

POST /api/v2/entries
Request  Create Entry with Title
HideShow
Headers
Content-Type: application/json
Body
{
  "project_id": "36272",
  "title": "Luke's Private Entry"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "project location of the entry"
    },
    "title": {
      "type": "string",
      "description": "the display name of the entry"
    }
  },
  "required": [
    "project_id",
    "title"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /entries/10945
Body
{
  "id": "2309878",
  "version_id": "5309878",
  "author_id": "11038",
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "element_layout": {
    "rows": []
  },
  "elements": [],
  "tags": [],
  "custom_dates": [],
  "project_id": "36272",
  "title": "Luke's Private Entry",
  "entry_number": 1,
  "hidden": false,
  "editable": true,
  "last_editor_id": "11038",
  "author": {
    "id": "11038",
    "email": "luke.skywalker@starwars.com",
    "deactivated": false,
    "first_name": "Luke",
    "last_name": "Skywalker",
    "profile_picture_hash": "bhOwHTKEjrPTDeiMtTnc",
    "iam_id": "d229cc70-455d-421d-9938-b2d8b4dee79e"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the stable pointer to the most current version `blockId`"
    },
    "version_id": {
      "type": "string",
      "description": "the unique id of the entry"
    },
    "author_id": {
      "type": "string",
      "description": "the unique id of the user created the entry"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the entry was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when this entry was last modified"
    },
    "element_layout": {
      "type": "object",
      "properties": {
        "rows": {
          "type": "array",
          "description": "the notebook row/column layout of elements in the entry"
        }
      },
      "description": "The layout of the elements in this entry"
    },
    "elements": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {}
      },
      "description": "The elements in this entry"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {}
      },
      "description": "The tags for this entry. Tags are case insensitive."
    },
    "custom_dates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {}
      },
      "description": "Custom dates for this entry"
    },
    "project_id": {
      "type": "string",
      "description": "project location of the entry"
    },
    "title": {
      "type": "string",
      "description": "the display name of the entry"
    },
    "entry_number": {
      "type": "number",
      "description": "position of the entry inside the project"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicates if the entry is hidden or visible"
    },
    "editable": {
      "type": "boolean",
      "description": "Indicates if the requesting user has write access to the entry. An entry is editable if the user is the entry author while the entry is neither signed nor hidden."
    },
    "last_editor_id": {
      "type": "string",
      "description": "the unique id of the last user who made a modification to the entry"
    },
    "author": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "id of the user"
        },
        "email": {
          "type": "string",
          "description": "email of the user"
        },
        "deactivated": {
          "type": "boolean",
          "description": "the flags shows if the user's account is deactivated"
        },
        "first_name": {
          "type": "string",
          "description": "first name of the user"
        },
        "last_name": {
          "type": "string",
          "description": "last name of the user"
        },
        "profile_picture_hash": {
          "type": [
            "string",
            "null"
          ],
          "description": "a hash to be used for the profile picture location url"
        },
        "iam_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "user uuid identifying the user in IAM"
        }
      },
      "required": [
        "id",
        "email",
        "deactivated",
        "first_name",
        "last_name",
        "profile_picture_hash",
        "iam_id"
      ],
      "additionalProperties": false,
      "description": "the user who created the entry"
    }
  },
  "required": [
    "id",
    "version_id",
    "author_id",
    "creation_date",
    "version_date",
    "element_layout",
    "elements",
    "tags",
    "custom_dates",
    "project_id",
    "title",
    "entry_number",
    "hidden",
    "editable",
    "last_editor_id"
  ],
  "additionalProperties": false
}
Request  Create Entry with Tags
HideShow
Headers
Content-Type: application/json
Body
{
  "project_id": "36272",
  "title": "Luke's Private Entry",
  "tags": [
    "luke",
    "star wars"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "project location of the entry"
    },
    "title": {
      "type": "string",
      "description": "the display name of the entry"
    },
    "tags": {
      "type": "array",
      "items": [
        {
          "type": "string"
        },
        {
          "type": "string"
        }
      ],
      "description": "array of strings representing tags"
    }
  },
  "required": [
    "project_id",
    "title",
    "tags"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /entries/10945
Body
{
  "id": "2309878",
  "version_id": "5309878",
  "author_id": "11038",
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "element_layout": {
    "rows": []
  },
  "elements": [],
  "tags": [
    "luke",
    "star wars"
  ],
  "custom_dates": [],
  "project_id": "36272",
  "title": "Luke's Private Entry",
  "entry_number": 1,
  "hidden": false,
  "editable": true,
  "last_editor_id": "11038",
  "author": {
    "id": "11038",
    "email": "luke.skywalker@starwars.com",
    "deactivated": false,
    "first_name": "Luke",
    "last_name": "Skywalker",
    "profile_picture_hash": "bhOwHTKEjrPTDeiMtTnc",
    "iam_id": "d229cc70-455d-421d-9938-b2d8b4dee79e"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the stable pointer to the most current version `blockId`"
    },
    "version_id": {
      "type": "string",
      "description": "the unique id of the entry"
    },
    "author_id": {
      "type": "string",
      "description": "the unique id of the user created the entry"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the entry was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when this entry was last modified"
    },
    "element_layout": {
      "type": "object",
      "properties": {
        "rows": {
          "type": "array",
          "description": "the notebook row/column layout of elements in the entry"
        }
      },
      "description": "The layout of the elements in this entry"
    },
    "elements": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {}
      },
      "description": "The elements in this entry"
    },
    "tags": {
      "type": "array",
      "items": [
        {
          "type": "string"
        },
        {
          "type": "string"
        }
      ],
      "description": "The tags for this entry. Tags are case insensitive."
    },
    "custom_dates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {}
      },
      "description": "Custom dates for this entry"
    },
    "project_id": {
      "type": "string",
      "description": "project location of the entry"
    },
    "title": {
      "type": "string",
      "description": "the display name of the entry"
    },
    "entry_number": {
      "type": "number",
      "description": "position of the entry inside the project"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicates if the entry is hidden or visible"
    },
    "editable": {
      "type": "boolean",
      "description": "Indicates if the requesting user has write access to the entry. An entry is editable if the user is the entry author while the entry is neither signed nor hidden."
    },
    "last_editor_id": {
      "type": "string",
      "description": "the unique id of the last user who made a modification to the entry"
    },
    "author": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "id of the user"
        },
        "email": {
          "type": "string",
          "description": "email of the user"
        },
        "deactivated": {
          "type": "boolean",
          "description": "the flags shows if the user's account is deactivated"
        },
        "first_name": {
          "type": "string",
          "description": "first name of the user"
        },
        "last_name": {
          "type": "string",
          "description": "last name of the user"
        },
        "profile_picture_hash": {
          "type": [
            "string",
            "null"
          ],
          "description": "a hash to be used for the profile picture location url"
        },
        "iam_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "user uuid identifying the user in IAM"
        }
      },
      "required": [
        "id",
        "email",
        "deactivated",
        "first_name",
        "last_name",
        "profile_picture_hash",
        "iam_id"
      ],
      "additionalProperties": false,
      "description": "the user who created the entry"
    }
  },
  "required": [
    "id",
    "version_id",
    "author_id",
    "creation_date",
    "version_date",
    "element_layout",
    "elements",
    "tags",
    "custom_dates",
    "project_id",
    "title",
    "entry_number",
    "hidden",
    "editable",
    "last_editor_id"
  ],
  "additionalProperties": false
}
Request  Create Entry with Custom Dates
HideShow
Headers
Content-Type: application/json
Body
{
  "project_id": "36272",
  "title": "Luke's Private Entry",
  "custom_dates": [
    {
      "name": "validation date",
      "value": "2017-12-25"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "project location of the entry"
    },
    "title": {
      "type": "string",
      "description": "the display name of the entry"
    },
    "custom_dates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of the custom date. Names are case insensitive."
          },
          "value": {
            "type": "string",
            "description": "The value of this custom date"
          }
        },
        "required": [
          "name",
          "value"
        ]
      },
      "description": "array of custom dates"
    }
  },
  "required": [
    "project_id",
    "title",
    "custom_dates"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /entries/10945
Body
{
  "id": "2309878",
  "version_id": "5309878",
  "author_id": "11038",
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "element_layout": {
    "rows": []
  },
  "elements": [],
  "tags": [],
  "custom_dates": [
    {
      "name": "validation date",
      "value": "2017-12-25"
    }
  ],
  "project_id": "36272",
  "title": "Luke's Private Entry",
  "entry_number": 1,
  "hidden": false,
  "editable": true,
  "last_editor_id": "11038",
  "author": {
    "id": "11038",
    "email": "luke.skywalker@starwars.com",
    "deactivated": false,
    "first_name": "Luke",
    "last_name": "Skywalker",
    "profile_picture_hash": "bhOwHTKEjrPTDeiMtTnc",
    "iam_id": "d229cc70-455d-421d-9938-b2d8b4dee79e"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the stable pointer to the most current version `blockId`"
    },
    "version_id": {
      "type": "string",
      "description": "the unique id of the entry"
    },
    "author_id": {
      "type": "string",
      "description": "the unique id of the user created the entry"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the entry was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when this entry was last modified"
    },
    "element_layout": {
      "type": "object",
      "properties": {
        "rows": {
          "type": "array",
          "description": "the notebook row/column layout of elements in the entry"
        }
      },
      "description": "The layout of the elements in this entry"
    },
    "elements": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {}
      },
      "description": "The elements in this entry"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {}
      },
      "description": "The tags for this entry. Tags are case insensitive."
    },
    "custom_dates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of the custom date. Names are case insensitive."
          },
          "value": {
            "type": "string",
            "description": "The value of this custom date"
          }
        },
        "required": [
          "name",
          "value"
        ]
      },
      "description": "Custom dates for this entry"
    },
    "project_id": {
      "type": "string",
      "description": "project location of the entry"
    },
    "title": {
      "type": "string",
      "description": "the display name of the entry"
    },
    "entry_number": {
      "type": "number",
      "description": "position of the entry inside the project"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicates if the entry is hidden or visible"
    },
    "editable": {
      "type": "boolean",
      "description": "Indicates if the requesting user has write access to the entry. An entry is editable if the user is the entry author while the entry is neither signed nor hidden."
    },
    "last_editor_id": {
      "type": "string",
      "description": "the unique id of the last user who made a modification to the entry"
    },
    "author": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "id of the user"
        },
        "email": {
          "type": "string",
          "description": "email of the user"
        },
        "deactivated": {
          "type": "boolean",
          "description": "the flags shows if the user's account is deactivated"
        },
        "first_name": {
          "type": "string",
          "description": "first name of the user"
        },
        "last_name": {
          "type": "string",
          "description": "last name of the user"
        },
        "profile_picture_hash": {
          "type": [
            "string",
            "null"
          ],
          "description": "a hash to be used for the profile picture location url"
        },
        "iam_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "user uuid identifying the user in IAM"
        }
      },
      "required": [
        "id",
        "email",
        "deactivated",
        "first_name",
        "last_name",
        "profile_picture_hash",
        "iam_id"
      ],
      "additionalProperties": false,
      "description": "the user who created the entry"
    }
  },
  "required": [
    "id",
    "version_id",
    "author_id",
    "creation_date",
    "version_date",
    "element_layout",
    "elements",
    "tags",
    "custom_dates",
    "project_id",
    "title",
    "entry_number",
    "hidden",
    "editable",
    "last_editor_id"
  ],
  "additionalProperties": false
}
Request  Create Entry from an Existing Entry or Template
HideShow

Creates a new entry in the target project using the notebook entry or template entry identified by the Source-Id header. Providing the Source-Id header causes all additional fields, other than project_id, to be omitted for the creation. Note that the target project must exist within the same group as that of the source notebook entry or template entry.

Headers
Content-Type: application/json
Source-Id: 938302
Body
{
  "project_id": "36272"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "project location of the entry"
    }
  },
  "required": [
    "project_id"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: /entries/10945
Body
{
  "id": "2309878",
  "version_id": "5309878",
  "author_id": "11038",
  "creation_date": "2017-02-10T12:34:56.789+0200",
  "version_date": "2017-02-15T12:34:56.789+0200",
  "element_layout": {
    "rows": []
  },
  "elements": [],
  "tags": [],
  "custom_dates": [],
  "project_id": "36272",
  "title": "Luke's Private Entry",
  "entry_number": 1,
  "hidden": false,
  "editable": true,
  "last_editor_id": "11038",
  "author": {
    "id": "11038",
    "email": "luke.skywalker@starwars.com",
    "deactivated": false,
    "first_name": "Luke",
    "last_name": "Skywalker",
    "profile_picture_hash": "bhOwHTKEjrPTDeiMtTnc",
    "iam_id": "d229cc70-455d-421d-9938-b2d8b4dee79e"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the stable pointer to the most current version `blockId`"
    },
    "version_id": {
      "type": "string",
      "description": "the unique id of the entry"
    },
    "author_id": {
      "type": "string",
      "description": "the unique id of the user created the entry"
    },
    "creation_date": {
      "type": "string",
      "description": "date when the entry was created"
    },
    "version_date": {
      "type": "string",
      "description": "date when this entry was last modified"
    },
    "element_layout": {
      "type": "object",
      "properties": {
        "rows": {
          "type": "array",
          "description": "the notebook row/column layout of elements in the entry"
        }
      },
      "description": "The layout of the elements in this entry"
    },
    "elements": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {}
      },
      "description": "The elements in this entry"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {}
      },
      "description": "The tags for this entry. Tags are case insensitive."
    },
    "custom_dates": {
      "type": "array",
      "description": "Custom dates for this entry"
    },
    "project_id": {
      "type": "string",
      "description": "project location of the entry"
    },
    "title": {
      "type": "string",
      "description": "the display name of the entry"
    },
    "entry_number": {
      "type": "number",
      "description": "position of the entry inside the project"
    },
    "hidden": {
      "type": "boolean",
      "description": "indicates if the entry is hidden or visible"
    },
    "editable": {
      "type": "boolean",
      "description": "Indicates if the requesting user has write access to the entry. An entry is editable if the user is the entry author while the entry is neither signed nor hidden."
    },
    "last_editor_id": {
      "type": "string",
      "description": "the unique id of the last user who made a modification to the entry"
    },
    "author": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "id of the user"
        },
        "email": {
          "type": "string",
          "description": "email of the user"
        },
        "deactivated": {
          "type": "boolean",
          "description": "the flags shows if the user's account is deactivated"
        },
        "first_name": {
          "type": "string",
          "description": "first name of the user"
        },
        "last_name": {
          "type": "string",
          "description": "last name of the user"
        },
        "profile_picture_hash": {
          "type": [
            "string",
            "null"
          ],
          "description": "a hash to be used for the profile picture location url"
        },
        "iam_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "user uuid identifying the user in IAM"
        }
      },
      "required": [
        "id",
        "email",
        "deactivated",
        "first_name",
        "last_name",
        "profile_picture_hash",
        "iam_id"
      ],
      "additionalProperties": false,
      "description": "the user who created the entry"
    }
  },
  "required": [
    "id",
    "version_id",
    "author_id",
    "creation_date",
    "version_date",
    "element_layout",
    "elements",
    "tags",
    "custom_dates",
    "project_id",
    "title",
    "entry_number",
    "hidden",
    "editable",
    "last_editor_id"
  ],
  "additionalProperties": false
}

Update Entry
PATCH/entries/{id}

Update an entry’s attributes. The supported operations will grow in time. This endpoint complies with RFC 6902, the specification for JSON Patch.

Example URI

PATCH /api/v2/entries/938306
URI Parameters
HideShow
id
string (required) Example: 938306

the unique id of the entry

Request  Change the Project of an Entry
HideShow

Note: the Project must exist in the same workspace as the entry for the operation to be successful.

Headers
Content-Type: application/json-patch+json
Body
[
  {
    "op": "replace",
    "path": "/project_id",
    "value": "36272"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "op": {
        "type": "string",
        "enum": [
          "replace"
        ],
        "description": "The replace operation defined by RFC 6902"
      },
      "path": {
        "type": "string",
        "enum": [
          "/project_id"
        ],
        "description": "JSON Pointer notation to the member named project id"
      },
      "value": {
        "type": "string",
        "description": "the id of the project, in which the entry should move"
      }
    },
    "required": [
      "op",
      "path",
      "value"
    ]
  }
}
Response  200
HideShow
Headers
Content-Type