Help Search

Edit on github

Folders Create

To create a new Folder, make a POST request to /folders.json with the folder data in request body.

POST /folders.json

Request data

The request body expects the following request data

Parameter Description Required Validation Constraints
folder_parent_id Folder parent id Yes
  1. Valid UUID
  2. Folder exists
name The name of the new folder Yes
  1. Valid UTF8 string
  2. Not empty
  3. Maximum 64 chars

Possible responses

Code Description
200 OK
The Folder was created. The response body will contain the newly created folder object
400 Bad Request
Some of the data validation failed.
403 Authentication Failure
The folder making the request is not authenticated

Examples

Successful request

A valid request body, to create a folder at the root, will look like:

POST /folders.json?contain[permission]=1

{
  "folder_parent_id":null,
  "name":"New folder"
}

Success response

{
    "header": {
        "id": "88124489-f8e6-44f7-b985-87c5b26c9b4c",
        "status": "success",
        "servertime": 1619761096,
        "action": "02e18a01-42f6-5e5d-b18f-2ee9070e3b9d",
        "message": "The folder `New folder` has been added successfully.",
        "url": "\/folders.json?contain%5Bpermission%5D=1",
        "code": 200
    },
    "body": {
        "id": "b6cfc5e5-138d-467a-a615-a852f1c747ae",
        "name": "New folder",
        "created": "2021-04-30T05:38:16+00:00",
        "modified": "2021-04-30T05:38:16+00:00",
        "created_by": "f848277c-5398-58f8-a82a-72397af2d450",
        "modified_by": "f848277c-5398-58f8-a82a-72397af2d450",
        "permission": {
            "id": "66269af3-ddf1-4778-88ad-cc44573a097b",
            "aco": "Folder",
            "aco_foreign_key": "b6cfc5e5-138d-467a-a615-a852f1c747ae",
            "aro": "User",
            "aro_foreign_key": "f848277c-5398-58f8-a82a-72397af2d450",
            "type": 15,
            "created": "2021-04-30T05:38:16+00:00",
            "modified": "2021-04-30T05:38:16+00:00"
        },
        "folder_parent_id": null,
        "personal": true
    }
}

Validation error response

A successful request must pass all the validation checks. For example sending a blank request body will return:

{
    "header": {
        "id": "a91e1c30-568f-4889-8eec-dd78c0a00543",
        "status": "error",
        "servertime": 1554981597,
        "action": "a1a15b91-72f6-5708-8d7f-6940e51d8595",
        "message": "Could not validate folder data.",
        "url": "\/folders.json",
        "code": 400
    },
    "body": {
        "name": {
            "_required": "A name is required"
        }
    }
}

Last updated

This article was last updated on April 29th, 2021.

For another perspective on the API you browse the OpenAPI 2.0 specifications using the dedicated API reference site (Swagger UI).

API Reference

You can also find the latest OpenAPI 2.0 specifications directly on the dedicated repository.

OpenAPI Specs repository