Catenda Rest API v2 Development
Introduction
Any REST API's listed here is currently under development, and might change. Do NOT build production application based on these API's.
Note: Although, being under development, these API's connects to the production database!
Objects
This describes the objects that are sent, as well as returned from the resources of the API.
Custom field
Description
Represents a single custom field.
Fields
| Name | Type | Description |
|---|---|---|
| id | String | A unique identifier for a custom field. Represented as compacted UUID using 32 hexadecimal characters. |
| name | String | The name of the custom field. |
| description | String | Description of the custom field |
| type | String | text, integer, double, enumeration or date |
| createdAt | Date | The date and time the custom field was created |
| createdBy | String | A unique identifier of the User who created the custom field |
| archived | Boolean | Flag indicating if the custom field is archived |
Custom field enumeration item
Description
Represents an enumeration item of a custom field of type enumeration.
Fields
| Name | Type | Description |
|---|---|---|
| id | String | A unique identifier for an enumeration item. Represented as compacted UUID using 32 hexadecimal characters |
| name | String | The name of the item |
| code | String | Optional. The code of the item and if set, unique for a custom field. Used to identify the enumeration item if using document naming conventions |
| disabled | Boolean | Flag indicating if the enumeration item is disabled |
Enumeration item identifier
Description
An object representing an existing enumeration item as input.
Fields
| Name | Type | Description |
|---|---|---|
| id | String | A unique identifier for an enumeration item. Represented as compacted UUID using 32 hexadecimal characters |
Enumeration item move
Description
An object representing the reordering of an existing enumeration item.
Fields
| Name | Type | Description |
|---|---|---|
| id | String | A unique identifier for an existing enumeration item. Represented as compacted UUID using 32 hexadecimal characters |
| itemBeforeId | String or null | A unique identifier for an the existing enumeration item thatshould be in front of the moved item. Should be null if moved to the first position |
Enumeration item new name
Description
An object representing the input of a new name for an existing enumeration item.
Fields
| Name | Type | Description |
|---|---|---|
| id | String | A unique identifier for an enumeration item. Represented as compacted UUID using 32 hexadecimal characters |
| name | String | The new name. |
Enumeration item new code
Description
An object representing the input of a new code for an existing enumeration item.
Fields
| Name | Type | Description |
|---|---|---|
| id | String | A unique identifier for an enumeration item. Represented as compacted UUID using 32 hexadecimal characters |
| code | String | The new code. |
Custom field instance
Description
Represents an instance of a custom field.
Fields
| Name | Type | Description |
|---|---|---|
| id | String | A unique identifier for a custom field instance. Represented as compacted UUID using 32 hexadecimal characters |
| disabled | Boolean | Flag indicating if this instance is disabled |
| required | Boolean | Flag indicating if the custom field instance should always have a value in an issue |
| defaultValue | Object | Optional if required is false. Default value for this custom field instance, based on the custom field type. |
| itemBeforeId | String | Unique identifier of the custom field instance that appears before the current one. Should be null if the item is the first one. |
New custom field instance
Description
Represents an input of a custom field instance to be created.
Fields
| Name | Type | Description |
|---|---|---|
| id | String | A unique identifier for an existing custom field. Represented as compacted UUID using 32 hexadecimal characters |
| required | Boolean | Boolean flag representing if the custom field instance should always have a value |
| defaultValue | Object | Default value for the custom field instance, but optional if required flag is false. Should match the type of the existing custom field. Possible values: null, Date, double, integer, enumeration item id, string |
Update custom field instance
Description
Represents an input of a custom field instance to be updated.
Fields
| Name | Type | Description |
|---|---|---|
| id | String | A unique identifier for an existing custom field instance. Represented as compacted UUID using 32 hexadecimal characters |
| required | Boolean | Boolean flag representing if the custom field instance should always have a value |
| defaultValue | Object | Default value for the custom field instance, but optional if required flag is false. Should match the type of the existing custom field. Possible values: null, Date, double, integer, enumeration item id, string |
Custom field instance identifier
Description
An object representing an existing custom field instance as input.
Fields
| Name | Type | Description |
|---|---|---|
| id | String | A unique identifier for a custom field instance. Represented as compacted UUID using 32 hexadecimal characters |
Custom field instance item move
Description
An object representing the reordering of an existing custom field instance.
Fields
| Name | Type | Description |
|---|---|---|
| id | String | A unique identifier for an existing custom field instance. Represented as compacted UUID using 32 hexadecimal characters |
| itemBeforeId | String or null | A unique identifier for an the existing custom field instance that will be positioned before the current one. Should be null if the item is being moved to the first position |
Topic board
Description
Represents a single topic board
Fields
| Name | Type | Description |
|---|---|---|
| id | String | A unique identifier for an issue board. Represented as compacted UUID using 32 hexadecimal characters |
| name | String | The name of the topic board |
| description | String | The description of the issue board |
| customFields | Array of custom field | Collection of configured custom fields in the topic board. Only included by passing a query parameter (ex: Get topic board) |
| customFieldInstances | Array of custom field instance | Collection of custom field instances |
LibraryItemCollection
Description
Represents a library item collection (Currently only documents are supported). A collection is a group of a specific versions of library item files.
Fields
| Name | Type | Description |
|---|---|---|
| id | String | A unique identifier for a collection. Represented as compacted UUID using 32 hexadecimal characters. |
| name | String | The name of the collection. |
| description | String | The description of the collection. |
| finalized | boolean | If true, the collection is finalized. A finalized collection cannot be edited anymore. |
| followLatestRevision | boolean | If true, the collection items always follows the latest revisions. If false, the items are on the revision specified |
| visibility | String | Tells if if the collection is shared with the project or not. Possible values: 'private', 'project-members'. Will be auto set to 'project-members' when the collection is finalized |
| createdAt | Date | The date and time the collection was created. |
| createdBy | String | The user id of the user who created the collection. |
LibraryItemCollectionItem
Note: The Library item collection section is currently being implemented. This object is incomplete.
Description
Represents a library item collection item (Currently only documents are supported). An item is a specific version of a library item file.
Fields
| Name | Type | Description |
|---|---|---|
| id | String | The id of the collection item reference. |
| libraryId | String | The library id of the library item. (Only document library currently supported) |
| libraryItemId | String | The id of the library item. |
| fileId | String | The id of the library item file. (The document revision id) |
| createdAt | Date | The date and time the collection item was created. |
| createdBy | String | The user id of the user who created the collection item. |
Custom fields
List custom fields
Example
curl -X GET \
--header "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.catenda.com/v2/projects/af2d8af0fa54465b89bf26dd3d92cfd0/custom-fields"
Description
List all custom fields.
Method
GET
URL
https://api.catenda.com/v2/projects/:project/custom-fields
Query parameters
| Name | Type | Description |
|---|---|---|
| archived | String | Optional. Filter custom fields list based on their archived status. Possible values: all, archived, not-archived. Defaults to all if no value is provided. |
Response format
application/json
Response
Returns an array of custom fields.
Errors
| Status | Code | Message |
|---|---|---|
| 404 Not Found | 20 NOT_FOUND | Project (:project) not found |
Create custom field
Example
curl -X POST \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data-raw '{
"name": "Test",
"description": "My custom field",
"type": "text"
}' \
'https://api.catenda.com/v2/projects/af2d8af0fa54465b89bf26dd3d92cfd0/custom-fields'
Description
Creates a new custom field
Method
POST
URL
https://api.catenda.com/v2/projects/:project/custom-fields
Request parameters
| Name | Type | Description |
|---|---|---|
| name | String | The name of the custom field |
| description | String | Description of the custom field |
| type | String | 'text', 'integer', 'double', 'enumeration' or 'date' |
Request format
application/json
Response format
application/json
Response
Returns a custom field.
Errors
| Status | Code | Message |
|---|---|---|
| 404 Not Found | 20 NOT_FOUND | Project (:project) not found |
Get custom field
Example
curl -X GET \
--header "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.catenda.com/v2/projects/af2d8af0fa54465b89bf26dd3d92cfd0/custom-fields/f7a21acc13ec442ab9be660705aa4554"
Description
Get a custom field.
Method
GET
URL
https://api.catenda.com/v2/projects/:project/custom-fields/:id
Response format
application/json
Response
Returns a Custom Field.
Errors
| Status | Code | Message |
|---|---|---|
| 404 Not Found | 20 NOT_FOUND | Project (:project) not found or Custom field (:id) not found |
List custom field enumeration items
Example
curl -X GET \
--header "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.catenda.com/v2/projects/af2d8af0fa54465b89bf26dd3d92cfd0/custom-fields/f7a21acc13ec442ab9be660705aa4554/enumeration-items"
Description
Get the list of enumeration items of a given custom field.
Method
GET
URL
https://api.catenda.com/v2/projects/:project/custom-fields/:id/enumeration-items
Response format
application/json
Response
Returns an array of custom field enumeration items.
Errors
| Status | Code | Message |
|---|---|---|
| 404 Not Found | 20 NOT_FOUND | Project (:project) not found or Custom field (:id) not found |
Update custom field
Example
curl -X PATCH \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data-raw '{
"name": "Test updated name",
"description": "My custom field",
"enumerationItemsToAdd": [
{
"name": "Low",
"code": "l"
},
{
"name": "High",
"code": "h"
}
]
}' \
'https://api.catenda.com/v2/projects/af2d8af0fa54465b89bf26dd3d92cfd0/custom-fields/f7a21acc13ec442ab9be660705aa4554'
Description
Updates an existing custom field.
Method
PATCH
URL
https://api.catenda.com/v2/projects/:project/custom-fields/:id
Request parameters
| Name | Type | Description |
|---|---|---|
| name | String | The name of the custom field. |
| description | String | Description of the custom field |
| archived | Boolean | Optional. Can be true or false |
| enumerationItemsToAdd | Array of Object | Optional. Array of objects with 'name' and 'code' fields from custom field enumeration items |
| enumerationItemsToMove | Array of EnumerationItemMove | Optional. Items to reorder of the enumeration items |
| enumerationItemsToDisable | Array of EnumerationItemIdentifier | Optional. The enumeration items to disable |
| enumerationItemsToRestore | Array of EnumerationItemIdentifier | Optional. The enumeration items to restore |
| enumerationItemsToRename | Array of EnumerationItemNewName | Optional. The enumeration items with new names |
| enumerationItemsToUpdateCode | Array of EnumerationItemNewCode | Optional. The enumeration items with new codes |
Request format
application/json
Response format
application/json
Response
Returns a custom field.
Errors
| Status | Code | Message |
|---|---|---|
| 404 Not Found | 20 NOT_FOUND | Project (:project) not found |
| 409 Conflict | 600 conflict | Enumeration item already exists |
Topic Boards
Get topic board
Example
curl -X GET \
--header "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.catenda.com/v2/projects/af2d8af0fa54465b89bf26dd3d92cfd0/issues/boards/d8fa0be251be40b5bd9ed5c907cc40ec"
Description
Get a topic board given its id
Method
GET
URL
https://api.catenda.com/v2/projects/:project/issues/boards/:id
Query parameters
| Name | Type | Description |
|---|---|---|
| include | String | Optional. Comma separated list of referenced properties that will be added to the result item. Possible values: customFields |
Response format
application/json
Response
Returns an instance of a topic board.
Update topic board
Example
curl -X PATCH \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data-raw '{
"customFieldsToAdd": [
{
"id": "e9fb19148b504f769f02ba31922aa737",
"defaultValue": "Text"
}
]
}' \
'https://api.catenda.com/v2/projects/af2d8af0fa54465b89bf26dd3d92cfd0/issues/boards/d8fa0be251be40b5bd9ed5c907cc40ec'
Description
Updates the topic board's custom fields and instances.
Method
PATCH
URL
https://api.catenda.com/v2/projects/:project/issues/boards/:id
Query parameters
| Name | Type | Description |
|---|---|---|
| include | String | Optional. Comma separated list of referenced properties that will be added to the result item. Possible values: customFields |
Request parameters
| Name | Type | Description |
|---|---|---|
| customFieldsToAdd | Array of NewCustomFieldInstance | Optional. Array of objects representing custom field instances to create |
| customFieldsToModify | Array of [UpdateCustomFieldInstance] | Optional. Array of objects representing existing custom field instances to modify |
| customFieldsToDisable | Array of CustomFieldInstanceIdentifier | Optional. Array of objects representing existing custom field instances to disable |
| customFieldstoRestore | Array of CustomFieldInstanceIdentifier | Optional. Array of objects representing existing custom field instances to restore |
| customFieldsToDelete | Array of CustomFieldInstanceIdentifier | Optional. Array of objects representing existing custom field instances to delete |
| customFieldsToMove | Array of CustomFieldInstanceItemMove | Optional. Items to reorder of the custom field instances |
Request format
application/json
Response format
application/json
Response
Returns a custom field.
Errors
| Status | Code | Message |
|---|---|---|
| 404 Not Found | 20 NOT_FOUND | Project (:project) not found or IssueBoard (:issue-board) not found |
Libraries
List library item collections
Example
curl -X GET \
--header "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.catenda.com/v2/projects/af2d8af0fa54465b89bf26dd3d92cfd0/libraries/collections"
[
{
"id": "17f672533f734c22af29a8c9fe111e25",
"name": "My collection",
"description": "",
"finalized": false,
"visibility": "private",
"followLatestRevision": false,
"createdAt": "2023-01-17T07:54:20Z",
"createdBy": "fbd8c98942904c66abd871c8ee2c74dc"
}
]
Description
List all library item collections.
Method
GET
Query parameters
| Name | Type | Description |
|---|---|---|
| finalized | String | Optional. Possible values: 'true', 'false' |
| libraryItems | String | Optional comma separated list. If set returns only collections related to those libraryItem id's |
| files | String | Optional comma separated list. If set returns only collections related to those libraryItems file id's (document revisions) |
| createdAtFrom | String | Optional date on the iso 8601 format. Will filter the result to only contain items created after this date. |
| createdAtTo | String | Optional date on the iso 8601 format. Will filter the result to only contain items created before this date. |
| createdBy | String | Optional comma separated list. If set returns only collections created by the specified user ids |
| finalized | String | Optional. If set to "true", returns only collections that are finalized |
| followLatestRevision | String | Optional. If set to "true", returns only collections that follow the latest revisions of all library items (documents) |
| visibility | String | Optional comma separated list. if set, returns only collections with the specified visibility values. Possible values are 'private' and 'project-members' |
| sharedBy | String | Optional comma separated list. If set, returns only collections with the specified shared ways. Possible values are 'link', 'email' and 'not-shared' |
| followers | String | Optional comma separated list. If set, returns only collections that are followed by the specified user ids |
| search | String | Optional search text. Will filter the result to only contain collections whose name matches the search. |
| fields | String | Optional comma separated list. If set, specifies the fields to show on the response. Current supported values are 'id' |
URL
https://api.catenda.com/v2/projects/:project/libraries/collections
Response format
application/json
Response
Returns an array of LibraryItemCollection.
Errors
| Status | Code | Message |
|---|---|---|
| 404 Not Found | 20 NOT_FOUND | Project (:project) not found |
| 400 Bad Request | 24 BAD_REQUEST | Failed to parse date (:date). Must be on the iso 8601 format |
Get library item collection
Example
curl -X GET \
--header "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.catenda.com/v2/projects/af2d8af0fa54465b89bf26dd3d92cfd0/libraries/collections/17f672533f734c22af29a8c9fe111e25"
{
"id": "17f672533f734c22af29a8c9fe111e25",
"name": "My collection",
"description": "",
"finalized": false,
"visibility": "private",
"followLatestRevision": false,
"createdAt": "2023-01-17T07:54:20Z",
"createdBy": "fbd8c98942904c66abd871c8ee2c74dc"
}
Description
Get a library item collection.
Method
GET
URL
https://api.catenda.com/v2/projects/:project/libraries/collections/:collection
Response format
application/json
Response
Returns a LibraryItemCollection.
Errors
| Status | Code | Message |
|---|---|---|
| 404 Not Found | 20 NOT_FOUND | Project (:project) not found |
| 404 Not Found | 20 NOT_FOUND | Collection not found, id (:collection) |
Create library item collection
Example
curl -X POST \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data "{ \"name\": \"My 2nd collection\", \"description\": \"My description\", \"items\": [{ \"libraryId\": \"ead9b194e6024e6b92cae1d791797b68\", \"libraryItemId\": \"5badf33213ae420ebf81e727d5281850\", \"fileId\": \"5dc75452-29a4-4c4a-8415-991b92a92001\" }] }" \
"https://api.catenda.com/v2/projects/af2d8af0fa54465b89bf26dd3d92cfd0/libraries/collections"
{
"id": "27f672533f734c22af29a8c9fe111e26",
"name": "My 2nd collection",
"description": "My description",
"finalized": false,
"visibility": "private",
"followLatestRevision": false,
"createdAt": "2023-01-25T07:54:20Z",
"createdBy": "fbd8c98942904c66abd871c8ee2c74dc"
}
Description
Create a library item collection. This resource is supported for document library items only.
Method
POST
URL
https://api.catenda.com/v2/projects/:project/libraries/collections
Request parameters
| Name | Type | Description |
|---|---|---|
| name | String | The name of the library item collection. |
| description | String | Optional. The description of the library item collection. |
| items | Array of LibraryItemCollectionItem | Optional. List of items to add to the collection |
| followLatestRevision | boolean | Optional. Sets if the collection should always follow the latest revisions of the specified array of LibraryItemCollectionItem |
LibraryItemCollectionFile object:
| Name | Type | Description |
|---|---|---|
| libraryId | String | The library id of the library item. (Only document library currently supported) |
| libraryItemId | String | The id of the library item. |
| fileId | String | Optional. The id of the library item file. (The document revision id). If not set, will default to the latest document revision id. |
Request format
application/json
Response format
application/json
Response
Returns the created library collection. Note: the created collection items are not returned in the result. See: "List library item collection items"
Errors
| Status | Code | Message |
|---|---|---|
| 404 Not Found | 20 NOT_FOUND | Project (:project) not found |
| 404 Not Found | 20 NOT_FOUND | Library (:library) not found |
| 404 Not Found | 20 NOT_FOUND | Library item (:library-item) not found |
| 404 Not Found | 20 NOT_FOUND | Library item file (:file) not found |
| 403 Forbidden | 100 INSUFFICIENT_PRIVILEGE | Insufficient privilege |
Update library item collection
Example
curl -X PATCH \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data "{ \"name\": \"My finalized collection\", \"description\": \"My updated description\", \"finalized\": true, \"visibility\": \"project-members\", \"followLatestRevision\": true }" \
"https://api.catenda.com/v2/projects/af2d8af0fa54465b89bf26dd3d92cfd0/libraries/collections/27f672533f734c22af29a8c9fe111e26"
{
"id": "27f672533f734c22af29a8c9fe111e26",
"name": "My finalized collection",
"description": "My updated description",
"finalized": true,
"visibility": "project-members",
"followLatestRevision": true,
"createdAt": "2023-01-25T07:54:20Z",
"createdBy": "fbd8c98942904c66abd871c8ee2c74dc"
}
Description
Update a library item collection.
Method
PATCH
URL
https://api.catenda.com/v2/projects/:project/libraries/collections/:collection
Request parameters
| Name | Type | Description |
|---|---|---|
| name | String | Optional. The new name of the collection. |
| description | String | Optional. The new description of the collection. |
| finalized | boolean | Optional. If true, the collection will become finalized. A finalized collection cannot be edited anymore. |
| visibility | String | Optional. Tells if if the collection is shared with the project or not. Possible values: 'private', 'project-members'. Will be auto set to 'project-members' when the collection is finalized |
| shareExpiresAt | String | Optional date on the iso 8601 format. Will set the date that the shared public link expires |
| followLatestRevision | boolean | Optional. If true, the collection items always follows the latest revisions. If false, the items are on the revision specified |
Request format
application/json
Response format
application/json
Response
Returns the updated library collection.
Errors
| Status | Code | Message |
|---|---|---|
| 404 Not Found | 20 NOT_FOUND | Project (:project) not found |
| 403 Forbidden | 100 INSUFFICIENT_PRIVILEGE | Insufficient privilege |
List library item collection items
Example
curl -X GET \
--header "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.catenda.com/v2/projects/af2d8af0fa54465b89bf26dd3d92cfd0/libraries/collections/d3b93830a9214d578135179cf14ac538/items"
[
{
"id": "86ccce8943ee4fa9bf5c79f37c9cbd19",
"libraryId": "ead9b194e6024e6b92cae1d791797b68",
"libraryItemId": "5badf33213ae420ebf81e727d5281850",
"fileId": "5dc75452-29a4-4c4a-8415-991b92a92001",
"createdAt": "2023-01-25T13:34:14Z",
"createdBy": "fbd8c98942904c66abd871c8ee2c74dc"
}
]
Description
List all library item collection items.
Method
GET
Query parameters
| Name | Type | Description |
|---|---|---|
| fields | String | Optional comma separated list. If set, specifies the fields to show on the response. Current supported values are 'id' |
| include | String | Optional comma separated list. If set, specifies the additional fields to return with the response. Current supported values are 'libraryItem' |
| libraryItemInclude | String | Optional comma separated list. If set together with include=libraryItem, will specify the additional library item fields to return on the response. Current supported values are 'path' |
URL
https://api.catenda.com/v2/projects/:project/libraries/collections/:collection/items
Response format
application/json
Response
Returns an array of LibraryItemCollectionItem.
Errors
| Status | Code | Message |
|---|---|---|
| 404 Not Found | 20 NOT_FOUND | Project (:project) not found |
| 404 Not Found | 20 NOT_FOUND | Collection (:collection) not found |
Add or update library item collection items
Example
curl -X POST \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data "{ \"options\": { \"duplicateItemOption\": "overwrite-different-version" }, \"items\": [{ \"libraryId\": \"ead9b194e6024e6b92cae1d791797b68\", \"libraryItemId\": \"5badf33213ae420ebf81e727d5281850\", \"fileId\": \"1d95e3b4-f738-457e-b197-5ba10b5d5baa\" }] }" \
"https://api.catenda.com/v2/projects/af2d8af0fa54465b89bf26dd3d92cfd0/libraries/collections/d3b93830a9214d578135179cf14ac538/items"
{
"collection": {
"id": "d3b93830a9214d578135179cf14ac538",
"name": "Collection from API v2",
"description": "My description",
"finalized": false,
"visibility": "project-members",
"followLatestRevision": true,
"createdAt": "2023-01-25T13:34:14Z",
"createdBy": "fbd8c98942904c66abd871c8ee2c74dc"
},
"createdItems": [
{
"id": "e0faafd7fb284a3c8fc1a27854349e07",
"libraryId": "ead9b194e6024e6b92cae1d791797b68",
"libraryItemId": "5badf33213ae420ebf81e727d5281850",
"fileId": "1d95e3b4-f738-457e-b197-5ba10b5d5baa",
"createdAt": "2023-01-25T13:54:10Z",
"createdBy": "fbd8c98942904c66abd871c8ee2c74dc"
}
],
"removedItems": [
{
"id": "86ccce8943ee4fa9bf5c79f37c9cbd19",
"libraryId": "ead9b194e6024e6b92cae1d791797b68",
"libraryItemId": "5badf33213ae420ebf81e727d5281850",
"fileId": "5dc75452-29a4-4c4a-8415-991b92a92001",
"createdAt": "2023-01-25T13:34:14Z",
"createdBy": "fbd8c98942904c66abd871c8ee2c74dc"
}
],
"skippedItems": []
}
Description
Create/update one or many items of the library item collection . This resource is supported for document library items only.
Method
POST
URL
https://api.catenda.com/v2/projects/:project/libraries/collections/:collection/items
Request parameters
| Name | Type | Description |
|---|---|---|
| items | Array of LibraryItemCollectionItem | Items to add to the collection |
| options | Object | Optional AddItemOptions |
AddItemOptions object:
| Name | Type | Description |
|---|---|---|
| duplicateItemOption | String | Optional. Possible values are "overwrite-different-version", "skip-duplicate-with-same-version", "skip-duplicate-with-different-version" |
| libraryItemId | String | The id of the library item. |
| fileId | String | The id of the library item file. (The document revision id) |
The duplicateItemOption kicks in if you are adding a library item that already exists. (the same library item id)
| DuplicateItemOption value | Description |
|---|---|
| overwrite-different-version | Remove the existing item, and create the new if it has a different version |
| skip-duplicate-with-same-version | Allow existing items with the same version to be passed. Fail if the version does not match |
| skip-duplicate-with-different-version | Ignore existing items |
| [default] | Fail if the item already exists |
Request format
application/json
Response format
application/json
Response
Returns the list of created, removed and skipped items.
Errors
| Status | Code | Message |
|---|---|---|
| 404 Not Found | 20 NOT_FOUND | Project (:project) not found |
| 404 Not Found | 20 NOT_FOUND | Library (:library) not found |
| 404 Not Found | 20 NOT_FOUND | Library item (:library-item) not found |
| 404 Not Found | 20 NOT_FOUND | Library item file (:file) not found |
| 403 Forbidden | 100 INSUFFICIENT_PRIVILEGE | Insufficient privilege |
Remove library item collection items
Example
curl -X DELETE \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data "{ \"items\": [\"e0faafd7fb284a3c8fc1a27854349e07\", \"86ccce8943ee4fa9bf5c79f37c9cbd19\"] }" \
"https://api.catenda.com/v2/projects/af2d8af0fa54465b89bf26dd3d92cfd0/libraries/collections/d3b93830a9214d578135179cf14ac538/items"
Status: 204 No Content
Description
Remove one or many items from the library item collection.
Method
DELETE
URL
https://api.catenda.com/v2/projects/:project/libraries/collections/:collection/items
Request parameters
| Name | Type | Description |
|---|---|---|
| items | Array of String | Ids of items to remove from the collection |
Request format
application/json
Response
No content
Errors
| Status | Code | Message |
|---|---|---|
| 404 Not Found | 20 NOT_FOUND | Project (:project) not found |
| 404 Not Found | 20 NOT_FOUND | Library (:library) not found |
| 403 Forbidden | 100 INSUFFICIENT_PRIVILEGE | Insufficient privilege |
List Library item collection followers
Example
curl -X GET \
--header "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.catenda.com/v2/projects/af2d8af0fa54465b89bf26dd3d92cfd0/libraries/collections/27f672533f734c22af29a8c9fe111e26/followers"
[
{
"id": "fbd8c98942904c66abd871c8ee2c74dc",
"name": "King Kong",
"username": "king@catenda.no",
"email": "king@catenda.no",
"createdAt": "2022-10-03T21:58:18Z",
"avatarUrl": null,
"type": "user"
}
]
Description
List all the followers of a given library item collection
Method
GET
URL
https://api.catenda.com/v2/projects/:project/libraries/collections/:collection/followers
Response format
application/json
Response
Returns an array of user.
Errors
| Status | Code | Message |
|---|---|---|
| 404 Not Found | 20 NOT_FOUND | Project (:project) not found |
| 404 Not Found | 20 NOT_FOUND | Collection (:collection) not found |
Add follower to library item collection
Example
curl -X POST \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data "{ \"userId\": \"fbd8c98942904c66abd871c8ee2c74dc\" }" \
"https://api.catenda.com/v2/projects/af2d8af0fa54465b89bf26dd3d92cfd0/libraries/collections/27f672533f734c22af29a8c9fe111e26/followers"
{
"id": "fbd8c98942904c66abd871c8ee2c74dc",
"name": "King Kong",
"username": "king@catenda.no",
"email": "king@catenda.no",
"createdAt": "2022-10-03T21:58:18Z",
"avatarUrl": null,
"type": "user"
}
Description
Adds a new follower to a given library item collection. If the collection is private only the collection owner can add or itself as a follower. If the collection is project-shared normal users can add themselves as followers but only admins or collection owners can add any follower.
Method
POST
URL
https://api.catenda.com/v2/projects/:project/libraries/collections/:collection/followers
Request parameters
| Name | Type | Description |
|---|---|---|
| userId | String | User id of the user to follow the collection |
Request format
application/json
Response format
application/json
Response
Returns a user.
Errors
| Status | Code | Message |
|---|---|---|
| 404 Not Found | 20 NOT_FOUND | Project (:project) not found |
| 404 Not Found | 20 NOT_FOUND | Collection (:collection) not found |
| 404 Not Found | 20 NOT_FOUND | Could not find user to add as follower, id (:user) |
| 403 Forbidden | 21 FORBIDDEN | No permissions to modify followers, collection id (:collection) |
Remove library item collection follower
Example
curl -X DELETE \
--header "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.catenda.com/v2/projects/af2d8af0fa54465b89bf26dd3d92cfd0/libraries/collections/27f672533f734c22af29a8c9fe111e26/followers/fbd8c98942904c66abd871c8ee2c74dc"
Status: 204 No Content
Description
Removes one follower from the collection If the collection is private only the collection owner can remove itself as a follower. If the collection is project-shared normal users can remove themselves as followers but only admins or collection owners can remove any follower.
Method
DELETE
URL
https://api.catenda.com/v2/projects/:project/libraries/collections/:collection/followers/:user
Response
No content
Errors
| Status | Code | Message |
|---|---|---|
| 404 Not Found | 20 NOT_FOUND | Project (:project) not found |
| 404 Not Found | 20 NOT_FOUND | Collection (:collection) not found |
| 403 Forbidden | 21 FORBIDDEN | No permissions to modify followers, collection id (:collection) |
Batch update library item collection followers
Example
curl -X PATCH \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--data "{ \"followersToAdd\": [\"69254ba01b8c494f88b6054ad19a5b88\"], \"followersToRemove\": [\"fbd8c98942904c66abd871c8ee2c74dc\"]}" \
"https://api.catenda.com/v2/projects/af2d8af0fa54465b89bf26dd3d92cfd0/libraries/collections/27f672533f734c22af29a8c9fe111e26/followers/batch"
{
"followersAdded": [
"69254ba01b8c494f88b6054ad19a5b88"
],
"followersRemoved": [
"fbd8c98942904c66abd871c8ee2c74dc"
]
}
Description
Updates multiple followers on a given library item collection. Only a project admin or the collection owner can update the followers in batch.
URL
https://api.catenda.com/v2/projects/:project/libraries/collections/:collection/followers/batch
Method
PATCH
Request parameters
| Name | Type | Description |
|---|---|---|
| followersToAdd | Array | Array of strings of user ids to add as followers |
| followersToRemove | Array | Array of strings of user ids to remove as followers |
Request format
application/json
Response format
application/json
Response
Returns an object with the following fields:
| Name | Type | Description |
|---|---|---|
| followersAdded | Array | Array of strings of user ids that were added as followers |
| followersRemoved | Array | ARray of strings of user ids that were removed as followers |
Errors
| Status | Code | Message |
|---|---|---|
| 404 Not Found | 20 NOT_FOUND | Project (:project) not found |
| 404 Not Found | 20 NOT_FOUND | Collection (:collection) not found |
| 404 Not Found | 20 NOT_FOUND | Followers not found, ids (:users) |
| 403 Forbidden | 21 FORBIDDEN | No permissions to modify followers, collection id (:collection) |
| 400 Bad request | 24 BAD_REQUEST | Followers cannot be both added and removed in the same request, ids (:users) |