Skip to main content

Create a new dashboard

POST 
/perses-public/api/v1/projects/:projectId/dashboards

Creates a dashboard in the given folder.

The request body wraps a complete Perses dashboard document in a doc property. Only doc.metadata.name is validated, and it is required: it is the dashboard's identity and the value both search endpoints match on. The title shown in the app is doc.spec.display.name. The rest of doc.spec is stored as sent, so it has to be a valid Perses dashboard spec for the dashboard to render.

Pass the literal ROOT_FOLDER as projectId to create the dashboard in the account's root folder, creating that folder if the account doesn't have one yet. This sentinel is accepted on this endpoint only; every other endpoint takes the folder's id.

The server sets doc.metadata.project from the path, so any value you send for it is replaced.

The dashboard comes back with version 1 and the same value for id, uid and name. Those three diverge as soon as the dashboard is updated, so store the uid.

Request​

Path Parameters

    projectId stringrequired

    The id of the folder to create the dashboard in, or the literal ROOT_FOLDER for the account's root folder.

Body

required
    doc objectrequired

    A Perses dashboard document. Only metadata.name is validated by Logz.io; spec is stored as sent and has to be a valid Perses dashboard spec for the dashboard to render in the app.

    kind stringrequired

    Possible values: [Dashboard]

    metadata objectrequired
    name stringrequired

    The dashboard's identity, and the only field both search endpoints match on. Required on create and update.

    project string

    Set by the server from the folder in the request path. Any value sent here is replaced.

    tags string[]
    spec objectrequired

    Extra properties are allowed. The Perses dashboard spec. See the Perses dashboard specification for the panel, layout and query plugin shapes.

    display object

    How the dashboard is labelled in the app.

    name string
    description string
    duration string

    Default time range, as a duration string.

    refreshInterval string

    Auto-refresh interval, as a duration string.

    variables object[]
    panels object

    Panel definitions, keyed by panel name.

    layouts object[]

    Grid layouts placing the panels.

    datasources object

    Datasources scoped to this dashboard, keyed by name.

Responses​

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

Schema
    uid string

    The dashboard's stable identifier. It survives updates and moves, and every endpoint addresses a dashboard by this value. This is the one to store.

    id string

    Identifier of the version row holding the current revision. A new value is issued on every update, and it can't be used to address the dashboard. A dashboard that has never been updated has the same value here as in uid, which makes the two easy to confuse.

    name string

    Internal marker for the dashboard, equal to uid for dashboards created through this API. The name shown in the app is doc.spec.display.name, and the name that search matches is doc.metadata.name.

    projectId string

    The id of the folder holding the dashboard.

    doc object

    A Perses dashboard document. Only metadata.name is validated by Logz.io; spec is stored as sent and has to be a valid Perses dashboard spec for the dashboard to render in the app.

    kind stringrequired

    Possible values: [Dashboard]

    metadata objectrequired
    name stringrequired

    The dashboard's identity, and the only field both search endpoints match on. Required on create and update.

    project string

    Set by the server from the folder in the request path. Any value sent here is replaced.

    tags string[]
    spec objectrequired

    Extra properties are allowed. The Perses dashboard spec. See the Perses dashboard specification for the panel, layout and query plugin shapes.

    display object

    How the dashboard is labelled in the app.

    name string
    description string
    duration string

    Default time range, as a duration string.

    refreshInterval string

    Auto-refresh interval, as a duration string.

    variables object[]
    panels object

    Panel definitions, keyed by panel name.

    layouts object[]

    Grid layouts placing the panels.

    datasources object

    Datasources scoped to this dashboard, keyed by name.

    version integer

    Revision number. Starts at 1 and increments on every update.

    createdBy integer

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

    updatedBy integer

    Numeric id of the principal that last updated the dashboard.

    createdAt date-time

    When this version was written. An update stamps a new value, so this is not the creation time of the original dashboard.

    updatedAt date-time
    isPrivate boolean

    Whether the dashboard was made private in the Logz.io app. Privacy can't be changed through this API, and dashboards created through it are never private.

    isDeleted boolean
    deletedAt date-time

    Null unless the dashboard was deleted.

    deletedBy integer

    Null unless the dashboard was deleted.

Loading...