Create dashboards folder

POST 
/perses-public/api/v1/projects

Creates a folder from a Perses project document.

kind must be Project, and both metadata.name and spec.display.name are required and must be non-empty. metadata.name is the folder's identity and has to be unique in the account; spec.display.name is the name shown in the app.

The document is stored as you sent it, so spec.display.description and any other Perses fields are kept.

If the account has a deleted folder with the same metadata.name, that folder is restored and returned with the document it had before, and the document you sent is ignored.

Request

application/json

Body

required

kind stringrequired

Possible values: [Project]

metadata objectrequired

name stringrequired

The folder's identity. Required, must be non-empty, and has to be unique within the account.

spec objectrequired
display objectrequired
How the folder is labelled in the app. Required on both create and update.
name stringrequired
The name shown in the app. Required, and must be non-empty. On an update it also becomes the folder's name.
description string

Responses

200

The folder that was created. This endpoint returns 200, not 201.

application/json

Schema

Schema

id string

The folder's identifier, and the only way to address it.

name string

The folder's name. Set from metadata.name when the folder is created, and replaced by spec.display.name on an update or by newProjectName on a rename.

doc object
A Perses project document. This is the request body for creating and updating a dashboard folder.
kind stringrequired
Possible values: [Project]
metadata objectrequired
name stringrequired
The folder's identity. Required, must be non-empty, and has to be unique within the account.
spec objectrequired
display objectrequired
How the folder is labelled in the app. Required on both create and update.
name stringrequired
The name shown in the app. Required, and must be non-empty. On an update it also becomes the folder's name.
description string
entityId integer

Internal handle for the account that owns the folder.

createdBy integer

Numeric id of the principal that created the folder. For a folder created through this API this is the id of the API token, not of a user.

updatedBy integer
createdAt date-time
updatedAt date-time
isDeleted boolean

Returned as true or false by create, update and rename, and as 1 or 0 by the list, get and search endpoints.

deletedAt date-time

Null unless the folder was deleted.

deletedBy integer

Null unless the folder was deleted.

Example (from schema)

{
  "id": "0b9f6e2a-3c1d-4e8f-9a7b-1c2d3e4f5a6b",
  "name": "team-dashboards",
  "doc": {
    "kind": "Project",
    "metadata": {
      "name": "team-dashboards"
    },
    "spec": {
      "display": {
        "name": "Team Dashboards",
        "description": "Dashboards owned by the platform team"
      }
    }
  },
  "entityId": 11111,
  "createdBy": 22222,
  "updatedBy": 22222,
  "createdAt": "2026-08-14T09:12:31.000Z",
  "updatedAt": "2026-08-14T09:12:31.000Z",
  "isDeleted": false,
  "deletedAt": "2026-09-15T09:37:20.025Z",
  "deletedBy": 0
}

400

The body isn't a valid Perses project document, or it names a folder that already exists.

The validator names the field it rejected, for example "kind" must be "Project": the body is a full Perses Project document or "spec.display.name" is required and must be a non-empty string. A duplicate name returns Folder with this name already exists.

application/json

Schema

Schema

statusCode integer
message string
requestId string

Quote this when contacting support about a failed request.

errorCode string

Null for most dashboard errors.

parameters object

Extra context for the error, when there is any.

Example (from schema)

{
  "statusCode": 400,
  "message": "Dashboard name is required",
  "requestId": "string",
  "errorCode": "string",
  "parameters": {}
}

401

The API token is missing or invalid.

application/json

Schema

Schema

statusCode integer
message string
requestId string

Quote this when contacting support about a failed request.

errorCode string

Null for most dashboard errors.

parameters object

Extra context for the error, when there is any.

Example (from schema)

{
  "statusCode": 400,
  "message": "Dashboard name is required",
  "requestId": "string",
  "errorCode": "string",
  "parameters": {}
}

Loading...