API: Grids

A grid is a layout for a page or a part of the page of the OpenProject application. It defines the structure (number of rows and number of columns) as well as the contents of the page.

The contents is defined by GridWidgets. While a GridWidget is it’s own type, it is not a resource in it’s own right as it is an intrinsic part of a Grid.

Depending on what page a grid is defined for, different widgets may be eligible to be placed on the grid. The page might also define the permissions needed for accessing, creating or modifying the grid.

Currently, the following pages employ grids:

  • /my/page: The my page every user has. Only a user can access or modify their “my page”.

The delete action is not yet supported

Actions

Link Description Condition
updateImmediately Directly perform edits on this grid Permission: depends on the page the grid is defined for
update Validate edits on the grid via a form resource before committing Permission: depends on the page the grid is defined for

Linked Properties

Link Description Type Constraints Supported operations Condition
self This grid Grid not null READ
page The url of the page the grid is defined for url not null READ / WRITE The page cannot be changed after the creation

Local Properties

Property Description Type Constraints Supported operations Condition
id Grid’s id Integer x > 0 READ
rowCount The number of rows the grid has Integer x > 0 READ/WRITE
columnCount The number of columns the grid has Integer x > 0 READ/WRITE
widgets The set of GridWidgets selected for the grid []GridWidget READ/WRITE The widgets cannot overlap
createdAt The time the grid was created DateTime READ  
updatedAt The time the grid was last updated DateTime READ  

GridWidget Properties

Property Description Type Constraints Supported operations Condition
identifier The kind of widget String not null READ/WRITE
startRow The row the widget starts at (1 based) Integer x > 0, x < rowCount of the grid, x < endRow READ/WRITE
endRow The row the widget ends. The widget’s area does not include the row itself. Integer x > 0, x <= rowCount of the grid, x > startRow READ/WRITE
startColumn The column the widget starts at (1 based) Integer x > 0, x < columnCount of the grid, x < endColumn READ/WRITE
endColumn The column the widget ends. The widget’s area does not include the column itself. Integer x > 0, x <= columnCount of the grid, x > startColumn READ/WRITE
options An options hash of values customizable by the widget JSON READ/WRITE

Methods

List grids

Lists all grids matching the provided filters and being part of the selected query page. The grids returned will also depend on the permissions of the requesting user.

offset
integer

optional query

Page number inside the requested collection.

Default:
1

Example:
25

pageSize
integer

optional query

Number of elements to display per page.

Default:
30

Example:
25

filters
string

optional query

JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. Currently supported filters are:

  • page: Filter grid by work package

Example:
[{ "page": { "operator": "=", "values": ["/my/page"] } }]

200

OK

{
  "_type": "Collection",
  "total": 1,
  "count": 1,
  "pageSize": 30,
  "offset": 1,
  "_embedded": {
    "elements": [
      {
        "_type": "Grid",
        "id": 2,
        "rowCount": 8,
        "columnCount": 5,
        "widgets": [
          {
            "_type": "GridWidget",
            "identifier": "time_entries_current_user",
            "startRow": 1,
            "endRow": 8,
            "startColumn": 1,
            "endColumn": 3
          },
          {
            "_type": "GridWidget",
            "identifier": "news",
            "startRow": 3,
            "endRow": 8,
            "startColumn": 4,
            "endColumn": 5
          },
          {
            "_type": "GridWidget",
            "identifier": "documents",
            "startRow": 1,
            "endRow": 3,
            "startColumn": 3,
            "endColumn": 6
          }
        ],
        "createdAt": "2018-12-03T16:58:30.297Z",
        "updatedAt": "2018-12-13T19:36:40.352Z",
        "_links": {
          "scope": {
            "href": "/my/page",
            "type": "text/html"
          },
          "updateImmediately": {
            "href": "/api/v3/grids/2",
            "method": "patch"
          },
          "update": {
            "href": "/api/v3/grids/2/form",
            "method": "post"
          },
          "self": {
            "href": "/api/v3/grids/2"
          }
        }
      }
    ]
  }
}
GridCollectionModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/PaginatedCollectionModel"
    },
    {
      "type": "object",
      "required": [
        "_embedded"
      ],
      "properties": {
        "_embedded": {
          "type": "object",
          "required": [
            "elements"
          ],
          "properties": {
            "elements": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/GridReadModel"
              }
            }
          }
        }
      }
    }
  ]
}

400

Returned if the client sends invalid request parameters e.g. filters

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
  "message": "Filters Invalid filter does not exist."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client is not logged in and login is required.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to view this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Create a grid

Creates a new grid applying the attributes provided in the body. The constraints applied to the grid depend on the page the grid is placed in which is why the create form end point should be used to be guided when wanting to create a grid.

No parameters 
{
  "rowCount": {
    "type": "integer",
    "description": "The number of rows the grid has",
    "minimum": 1
  },
  "columnCount": {
    "type": "integer",
    "description": "The number of columns the grid has",
    "minimum": 1
  },
  "widgets": {
    "type": "array",
    "description": "The set of `GridWidget`s selected for the grid.\n\n# Conditions\n\n- The widgets must not overlap.",
    "items": {
      "$ref": "#/components/schemas/GridWidgetModel"
    }
  },
  "_links": {
    "type": "object",
    "properties": {
      "scope": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "The location where this grid is used, usually represented as a relative URL."
          }
        ]
      }
    }
  }
}

201

Created

GridReadModel
{
  "type": "object",
  "required": [
    "_type",
    "id",
    "rowCount",
    "columnCount",
    "widgets",
    "_links"
  ],
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "Grid"
      ]
    },
    "id": {
      "type": "integer",
      "description": "Grid's id",
      "minimum": 1
    },
    "rowCount": {
      "type": "integer",
      "description": "The number of rows the grid has",
      "minimum": 1
    },
    "columnCount": {
      "type": "integer",
      "description": "The number of columns the grid has",
      "minimum": 1
    },
    "widgets": {
      "type": "array",
      "description": "The set of `GridWidget`s selected for the grid.\n\n# Conditions\n\n- The widgets must not overlap.",
      "items": {
        "$ref": "#/components/schemas/GridWidgetModel"
      }
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the grid was created."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the grid was last updated."
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "scope"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This grid.\n\n**Resource**: Grid"
            }
          ]
        },
        "attachments": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The attachment collection of this grid.\n\n**Resource**: AttachmentCollection"
            }
          ]
        },
        "addAttachment": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Link for adding an attachment to this grid."
            }
          ]
        },
        "scope": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The location where this grid is used, usually represented as a relative URL."
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Directly perform edits on this grid.\n\n# Conditions\n\n**Permission**: depends on the page the grid is defined for"
            }
          ]
        },
        "update": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Validate edits on the grid via a form resource before committing\n\n# Conditions\n\n**Permission**: depends on the page the grid is defined for"
            }
          ]
        },
        "delete": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Deletes this grid resource."
            }
          ]
        }
      }
    }
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: Depends on the page the grid is defined for.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"

{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

422

Returned if:

  • a constraint for a property was violated (PropertyConstraintViolation)

Grid create form

No parameters

200

OK

Get a grid

Fetches a single grid identified by its id.

id
integer

required path

Grid id

Example:
42

200

OK

{
  "_type": "Grid",
  "id": 2,
  "rowCount": 8,
  "columnCount": 5,
  "widgets": [
    {
      "_type": "GridWidget",
      "identifier": "tasks",
      "startRow": 1,
      "endRow": 8,
      "startColumn": 1,
      "endColumn": 3
    },
    {
      "_type": "GridWidget",
      "identifier": "news",
      "startRow": 3,
      "endRow": 8,
      "startColumn": 4,
      "endColumn": 5
    },
    {
      "_type": "GridWidget",
      "identifier": "documents",
      "startRow": 1,
      "endRow": 3,
      "startColumn": 3,
      "endColumn": 6
    }
  ],
  "createdAt": "2018-12-03T16:58:30.915Z",
  "updatedAt": "2018-12-13T19:36:40.588Z",
  "_links": {
    "self": {
      "href": "/api/v3/grids/2"
    },
    "attachments": {
      "href": "/api/v3/grids/2/attachments"
    },
    "addAttachment": {
      "href": "/api/v3/grids/2/attachments",
      "method": "post"
    },
    "scope": {
      "href": "/my/page",
      "type": "text/html"
    },
    "updateImmediately": {
      "href": "/api/v3/grids/2",
      "method": "patch"
    },
    "update": {
      "href": "/api/v3/grids/2/form",
      "method": "post"
    },
    "delete": {
      "href": "/api/v3/grids/2",
      "method": "delete"
    }
  }
}
GridReadModel
{
  "type": "object",
  "required": [
    "_type",
    "id",
    "rowCount",
    "columnCount",
    "widgets",
    "_links"
  ],
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "Grid"
      ]
    },
    "id": {
      "type": "integer",
      "description": "Grid's id",
      "minimum": 1
    },
    "rowCount": {
      "type": "integer",
      "description": "The number of rows the grid has",
      "minimum": 1
    },
    "columnCount": {
      "type": "integer",
      "description": "The number of columns the grid has",
      "minimum": 1
    },
    "widgets": {
      "type": "array",
      "description": "The set of `GridWidget`s selected for the grid.\n\n# Conditions\n\n- The widgets must not overlap.",
      "items": {
        "$ref": "#/components/schemas/GridWidgetModel"
      }
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the grid was created."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the grid was last updated."
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "scope"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This grid.\n\n**Resource**: Grid"
            }
          ]
        },
        "attachments": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The attachment collection of this grid.\n\n**Resource**: AttachmentCollection"
            }
          ]
        },
        "addAttachment": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Link for adding an attachment to this grid."
            }
          ]
        },
        "scope": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The location where this grid is used, usually represented as a relative URL."
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Directly perform edits on this grid.\n\n# Conditions\n\n**Permission**: depends on the page the grid is defined for"
            }
          ]
        },
        "update": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Validate edits on the grid via a form resource before committing\n\n# Conditions\n\n**Permission**: depends on the page the grid is defined for"
            }
          ]
        },
        "delete": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Deletes this grid resource."
            }
          ]
        }
      }
    }
  }
}

404

Returned if the Grid does not exist or if the user does not have permission to view it.

Required permission depends on the page the grid is defined for

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Update a grid

Updates the given grid by applying the attributes provided in the body. The constraints applied to the grid depend on the page the grid is placed in which is why the create form end point should be used to be guided when wanting to update a grid.

No parameters 
{
  "rowCount": {
    "type": "integer",
    "description": "The number of rows the grid has",
    "minimum": 1
  },
  "columnCount": {
    "type": "integer",
    "description": "The number of columns the grid has",
    "minimum": 1
  },
  "widgets": {
    "type": "array",
    "description": "The set of `GridWidget`s selected for the grid.\n\n# Conditions\n\n- The widgets must not overlap.",
    "items": {
      "$ref": "#/components/schemas/GridWidgetModel"
    }
  },
  "_links": {
    "type": "object",
    "properties": {
      "scope": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "The location where this grid is used, usually represented as a relative URL."
          }
        ]
      }
    }
  }
}

200

OK

{
  "_type": "Grid",
  "id": 2,
  "rowCount": 8,
  "columnCount": 5,
  "widgets": [
    {
      "_type": "GridWidget",
      "identifier": "tasks",
      "startRow": 1,
      "endRow": 8,
      "startColumn": 1,
      "endColumn": 3
    },
    {
      "_type": "GridWidget",
      "identifier": "news",
      "startRow": 3,
      "endRow": 8,
      "startColumn": 4,
      "endColumn": 5
    },
    {
      "_type": "GridWidget",
      "identifier": "documents",
      "startRow": 1,
      "endRow": 3,
      "startColumn": 3,
      "endColumn": 6
    }
  ],
  "createdAt": "2018-12-03T16:58:30.915Z",
  "updatedAt": "2018-12-13T19:36:40.588Z",
  "_links": {
    "self": {
      "href": "/api/v3/grids/2"
    },
    "attachments": {
      "href": "/api/v3/grids/2/attachments"
    },
    "addAttachment": {
      "href": "/api/v3/grids/2/attachments",
      "method": "post"
    },
    "scope": {
      "href": "/my/page",
      "type": "text/html"
    },
    "updateImmediately": {
      "href": "/api/v3/grids/2",
      "method": "patch"
    },
    "update": {
      "href": "/api/v3/grids/2/form",
      "method": "post"
    },
    "delete": {
      "href": "/api/v3/grids/2",
      "method": "delete"
    }
  }
}
GridReadModel
{
  "type": "object",
  "required": [
    "_type",
    "id",
    "rowCount",
    "columnCount",
    "widgets",
    "_links"
  ],
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "Grid"
      ]
    },
    "id": {
      "type": "integer",
      "description": "Grid's id",
      "minimum": 1
    },
    "rowCount": {
      "type": "integer",
      "description": "The number of rows the grid has",
      "minimum": 1
    },
    "columnCount": {
      "type": "integer",
      "description": "The number of columns the grid has",
      "minimum": 1
    },
    "widgets": {
      "type": "array",
      "description": "The set of `GridWidget`s selected for the grid.\n\n# Conditions\n\n- The widgets must not overlap.",
      "items": {
        "$ref": "#/components/schemas/GridWidgetModel"
      }
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the grid was created."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the grid was last updated."
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "scope"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This grid.\n\n**Resource**: Grid"
            }
          ]
        },
        "attachments": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The attachment collection of this grid.\n\n**Resource**: AttachmentCollection"
            }
          ]
        },
        "addAttachment": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Link for adding an attachment to this grid."
            }
          ]
        },
        "scope": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The location where this grid is used, usually represented as a relative URL."
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Directly perform edits on this grid.\n\n# Conditions\n\n**Permission**: depends on the page the grid is defined for"
            }
          ]
        },
        "update": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Validate edits on the grid via a form resource before committing\n\n# Conditions\n\n**Permission**: depends on the page the grid is defined for"
            }
          ]
        },
        "delete": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Deletes this grid resource."
            }
          ]
        }
      }
    }
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: The permission depends on the page the grid is placed in.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"

{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

422

Returned if:

  • a constraint for a property was violated (PropertyConstraintViolation)

Grid update form

id
integer

required path

ID of the grid being modified

Example:
1

200

OK

{
  "_embedded": {
    "payload": {
      "columnCount": 5,
      "rowCount": 6,
      "widgets": [
        {
          "_type": "GridWidget",
          "endColumn": 3,
          "endRow": 8,
          "identifier": "time_entries_current_user",
          "startColumn": 1,
          "startRow": 1
        },
        {
          "_type": "GridWidget",
          "endColumn": 5,
          "endRow": 8,
          "identifier": "news",
          "startColumn": 4,
          "startRow": 3
        },
        {
          "_type": "GridWidget",
          "endColumn": 6,
          "endRow": 3,
          "identifier": "documents",
          "startColumn": 3,
          "startRow": 1
        }
      ]
    },
    "schema": {
      "_links": {
      },
      "_type": "Schema",
      "columnCount": {
        "hasDefault": false,
        "name": "Number of columns",
        "required": true,
        "type": "Integer",
        "writable": true
      },
      "createdAt": {
        "hasDefault": false,
        "name": "Created on",
        "required": true,
        "type": "DateTime",
        "writable": false
      },
      "id": {
        "hasDefault": false,
        "name": "ID",
        "required": true,
        "type": "Integer",
        "writable": false
      },
      "rowCount": {
        "hasDefault": false,
        "name": "Number of rows",
        "required": true,
        "type": "Integer",
        "writable": true
      },
      "scope": {
        "_links": {
        },
        "hasDefault": false,
        "name": "Page",
        "required": true,
        "type": "Href",
        "writable": false
      },
      "updatedAt": {
        "hasDefault": false,
        "name": "Updated on",
        "required": true,
        "type": "DateTime",
        "writable": false
      },
      "widgets": {
        "_links": {
        },
        "hasDefault": false,
        "name": "Widgets",
        "required": true,
        "type": "[]GridWidget",
        "writable": true
      }
    },
    "validationErrors": {
      "widgets": {
        "_embedded": {
          "errors": [
            {
              "_embedded": {
                "details": {
                  "attribute": "widgets"
                }
              },
              "_type": "Error",
              "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
              "message": "Widgets is outside of the grid."
            },
            {
              "_embedded": {
                "details": {
                  "attribute": "widgets"
                }
              },
              "_type": "Error",
              "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
              "message": "Widgets is outside of the grid."
            }
          ]
        },
        "_type": "Error",
        "errorIdentifier": "urn:openproject-org:api:v3:errors:MultipleErrors",
        "message": "Multiple field constraints have been violated."
      }
    }
  },
  "_links": {
    "self": {
      "href": "/api/v3/grids/2/form",
      "method": "post"
    },
    "validate": {
      "href": "/api/v3/grids/2/form",
      "method": "post"
    }
  },
  "_type": "Form"
}

{
  "type": "object"
}

403

Returned if the client does not have sufficient permissions.

Required permission: depends on the page the grid is defined for.

Note that you will only receive this error, if you are at least allowed to see the corresponding grid.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the grid does not exist or the client does not have sufficient permissions to see it.

Required permission: view work package

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"

{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}