Checkout Resource

When a user checks out a file or folder it makes it so that other users cannot make modifications to the resource or its children until the resource is checked back in.

Check Out Request

POST {baseUrl}/spaces/{spaceId}/folders/{folderId}/checkout
POST {baseUrl}/spaces/{spaceId}/files/{fileId}/checkout

• HEADER:

  • Authorization: Bearer {tid token}

• BODY:

  • reason - User input string on why the resource is being checked out (Optional)

Example request body:

{
    "reason": "I need to make some changes"
}

After the checkout operation is completed, the JSON response returns the checked out file or folder.

Response

Example response:

{
    "id": "1d50bf0e-ede2-4ea9-9646-bfa3bb374812",
    "resourceTrn": "trn:2:fileservice:<region>:folder:1d50bf0e-ede2-4ea9-9646-bfa3bb374812",
    "name": "folder1",
    "parentId": "b93c5919-e3e8-47f9-bf26-d99c8864a19f",
    "checkout": {
        "checkedOutAt": "2025-09-21T17:48:40Z",
        "checkedOutByTrn": "trn:tid:user:6529d0b3-5856-41ab-88b3-86f7955cddf1",
        "reason": "Doing some work on this folder"
    },
    "permissionsLocal": {
        "acl": [
            {
                "actor": "trn:tid:user:6529d0b3-5856-41ab-88b3-86f7955cddf1",
                "role": "contentManager"
            },
            {
                "actor": "trn:tid:user:f85bc802-5481-4581-b972-c4652d595ec7",
                "role": "contentContributor"
            }
        ]
    },
    "createdAt": "2024-06-25T06:37:31Z",
    "createdByTrn": "trn:tid:application:<applicationId>",
    "updatedAt": "2024-06-25T06:37:31Z",
    "updatedByTrn": "trn:tid:application:<applicationId>",
    "path": "/folder1",
    "spaceId": "1edd3cf2-226c-42a0-b0d8-8fa828ed5d2b",
    "type": "FOLDER",
    "version": "1"
}

Check In Request

POST {baseUrl}/spaces/{spaceId}/folders/{folderId}/checkin
POST {baseUrl}/spaces/{spaceId}/files/{fileId}/checkin

• HEADER:

  • Authorization: Bearer {tid token}

• BODY:

  • Empty

  After the checkin operation is completed, the JSON response returns the checked out file or folder.

Response

Example response:

{
    "id": "1d50bf0e-ede2-4ea9-9646-bfa3bb374812",
    "resourceTrn": "trn:2:fileservice:<region>:folder:1d50bf0e-ede2-4ea9-9646-bfa3bb374812",
    "name": "folder1",
    "parentId": "b93c5919-e3e8-47f9-bf26-d99c8864a19f",
    "permissionsLocal": {
        "acl": [
            {
                "actor": "trn:tid:user:6529d0b3-5856-41ab-88b3-86f7955cddf1",
                "role": "contentManager"
            },
            {
                "actor": "trn:tid:user:f85bc802-5481-4581-b972-c4652d595ec7",
                "role": "contentContributor"
            }
        ]
    },
    "createdAt": "2024-06-25T06:37:31Z",
    "createdByTrn": "trn:tid:application:<applicationId>",
    "updatedAt": "2024-06-25T06:37:31Z",
    "updatedByTrn": "trn:tid:application:<applicationId>",
    "path": "/folder1",
    "spaceId": "1edd3cf2-226c-42a0-b0d8-8fa828ed5d2b",
    "type": "FOLDER",
    "version": "1"
}

Permissions

In order to lock a resource, users must have either the ContentContributor or ContentManager role. Users with ContentManager on a resource have the ability to check that resource back in even if it was checked out by a different user in order to prevent resources from being accidentally or maliciously locked permanently, for instance if a user owning a checkout leaves the company/project.

Advanced Behavior

Users are not prevented from checking out a folder which contains a child with a checkout from a different user. The new checkout of the parent will not apply to the checked out child resource, whose checkout remains unaffected, meaning the parent checkout owner will not be able to make changes to the child resource still. If the owner of the child checkout checks in that resource, then the parent checkout will automatically be applied to the child.

An example scenario would be that there exists folder1 with children file1 and file2. UserA checks out file1, and becomes the only user who can modify file1. UserB checks out folder1 which is allowed, but they can still not modify file1, only userA can. UserA cannot modify folder1 or file2, only userB can. Once userA checks in file1, it falls under the folder1 checkout, so only userB can modify folder1, file1, and file2, until they check in folder1.

Support Files

Support file creation and mutation are not blocked by checkouts in order for automated systems to work as intented. Modifications against master files are affected by checkouts which includes changes to its links attribute, so if an async process or application needs to be able to update master file links, it can be granted the SupportFileAdmin role in the Space ACL to allow it to bypass checkouts and update master file links.