Checkout Resource

When a user checks out a file, folder, or object 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
POST {baseUrl}/spaces/{spaceId}/objects/{objectId}/checkout

HEADER:
- Authorization: Bearer {tid token}
BODY:
- reason - User input string on why the resource is being checked out (Optional)

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

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

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": [
            {
                "id": "4bf84c79-47d4-4649-b242-334d97cbcf63",
                "actor": "trn:tid:user:6529d0b3-5856-41ab-88b3-86f7955cddf1",
                "role": "contentManager"
            },
            {
                "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "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
POST {baseUrl}/spaces/{spaceId}/objects/{objectId}/checkin

HEADER:
- Authorization: Bearer {tid token}
BODY:
- Empty
After the checkin operation is completed, the JSON response returns the checked out file, folder, or object.

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": [
            {
                "id": "4bf84c79-47d4-4649-b242-334d97cbcf63",
                "actor": "trn:tid:user:6529d0b3-5856-41ab-88b3-86f7955cddf1",
                "role": "contentManager"
            },
            {
                "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "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.

Objects behave the same as files within this hierarchy — as leaf nodes, they are protected by a parent folder checkout and can also be checked out independently.

Support Files

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