API: Labels

Labels can be attached to other resources, e.g. work packages.

Linked Properties

Link Description Type Constraints Supported operations
self This label Label not null READ

Local Properties

Property Description Type Constraints Supported operations
id Label id Integer x > 0 READ
name Label name String not empty READ / WRITE
createdAt The time the label was created DateTime READ
updatedAt The time the label was last updated DateTime READ

Methods

List all labels

Returns a paginated collection of labels, sorted by name.

filters
string

optional query

JSON specifying filter conditions. Currently supported filters are:

  • name: filters labels by name, with the operators ~ (contains), !~ (does not contain) and ** (all)

Example:
[{ "name": { "operator": "~", "values": ["bug"] } }]

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "self": {
            "href": "/api/v3/labels/1",
            "title": "Bug"
          }
        },
        "_type": "Label",
        "id": 1,
        "name": "Bug",
        "createdAt": "2014-08-29T12:40:53.373Z",
        "updatedAt": "2014-08-29T12:40:53.373Z"
      },
      {
        "_links": {
          "self": {
            "href": "/api/v3/labels/2",
            "title": "Frontend"
          }
        },
        "_type": "Label",
        "id": 2,
        "name": "Frontend",
        "createdAt": "2014-08-29T12:41:12.552Z",
        "updatedAt": "2014-08-29T12:41:12.552Z"
      },
      {
        "_links": {
          "self": {
            "href": "/api/v3/labels/3",
            "title": "Urgent"
          }
        },
        "_type": "Label",
        "id": 3,
        "name": "Urgent",
        "createdAt": "2014-08-29T12:42:03.128Z",
        "updatedAt": "2014-08-29T12:42:03.128Z"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/labels?filters=%5B%5D&offset=1&pageSize=20"
    },
    "jumpTo": {
      "href": "/api/v3/labels?filters=%5B%5D&offset=%7Boffset%7D&pageSize=20",
      "templated": true
    },
    "changeSize": {
      "href": "/api/v3/labels?filters=%5B%5D&offset=1&pageSize=%7Bsize%7D",
      "templated": true
    }
  },
  "_type": "Collection",
  "count": 3,
  "total": 3,
  "pageSize": 20,
  "offset": 1
}
LabelCollectionModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/OffsetPaginatedCollectionModel"
    },
    {
      "type": "object",
      "required": [
        "_links",
        "_embedded"
      ],
      "properties": {
        "_links": {
          "type": "object",
          "required": [
            "self"
          ],
          "properties": {
            "self": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "This label collection\n\n**Resource**: LabelCollectionModel",
                  "readOnly": true
                }
              ]
            }
          }
        },
        "_embedded": {
          "type": "object",
          "required": [
            "elements"
          ],
          "properties": {
            "elements": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/LabelModel"
              }
            }
          }
        }
      }
    }
  ]
}

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 does not have sufficient permissions.

Required permission: view work package (on any project)

{
  "_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."
    }
  }
}

Create label

Creates a label with the given name, or returns the existing label whose name matches case-insensitively. Leading, trailing and repeated whitespace in the name is collapsed before matching.

No parameters 
{
  "name": "Bug"
}

{
  "name": {
    "type": "string",
    "description": "Label name. Matched case-insensitively against existing labels.",
    "minLength": 1,
    "maxLength": 255
  }
}

200

OK. A label with that name already exists and is returned unchanged.

LabelModel
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Label id",
      "readOnly": true,
      "exclusiveMinimum": 0
    },
    "name": {
      "type": "string",
      "description": "Label name",
      "readOnly": true,
      "minLength": 1,
      "maxLength": 255
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the label was created",
      "readOnly": true
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the label was last updated",
      "readOnly": true
    },
    "_links": {
      "type": "object",
      "required": [
        "self"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This label\n\n**Resource**: Label",
              "readOnly": true
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "Label",
    "_links": {
      "self": {
        "href": "/api/v3/labels/1",
        "title": "Bug"
      }
    },
    "id": 1,
    "name": "Bug",
    "createdAt": "2014-08-29T12:40:53.373Z",
    "updatedAt": "2014-08-29T12:40:53.373Z"
  }
}

201

Created

LabelModel
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Label id",
      "readOnly": true,
      "exclusiveMinimum": 0
    },
    "name": {
      "type": "string",
      "description": "Label name",
      "readOnly": true,
      "minLength": 1,
      "maxLength": 255
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the label was created",
      "readOnly": true
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the label was last updated",
      "readOnly": true
    },
    "_links": {
      "type": "object",
      "required": [
        "self"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This label\n\n**Resource**: Label",
              "readOnly": true
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "Label",
    "_links": {
      "self": {
        "href": "/api/v3/labels/1",
        "title": "Bug"
      }
    },
    "id": 1,
    "name": "Bug",
    "createdAt": "2014-08-29T12:40:53.373Z",
    "updatedAt": "2014-08-29T12:40:53.373Z"
  }
}

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: edit work packages (on any project)

{
  "_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)
{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Name cannot be empty.",
  "_embedded": {
    "details": {
      "attribute": "name"
    }
  }
}
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."
    }
  }
}

View label

id
integer

required path

Label id

Example:
1

200

OK

{
  "_links": {
    "self": {
      "href": "/api/v3/labels/1",
      "title": "Bug"
    }
  },
  "_type": "Label",
  "id": 1,
  "name": "Bug",
  "createdAt": "2014-08-29T12:40:53.373Z",
  "updatedAt": "2014-08-29T12:40:53.373Z"
}
LabelModel
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Label id",
      "readOnly": true,
      "exclusiveMinimum": 0
    },
    "name": {
      "type": "string",
      "description": "Label name",
      "readOnly": true,
      "minLength": 1,
      "maxLength": 255
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the label was created",
      "readOnly": true
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the label was last updated",
      "readOnly": true
    },
    "_links": {
      "type": "object",
      "required": [
        "self"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This label\n\n**Resource**: Label",
              "readOnly": true
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "Label",
    "_links": {
      "self": {
        "href": "/api/v3/labels/1",
        "title": "Bug"
      }
    },
    "id": 1,
    "name": "Bug",
    "createdAt": "2014-08-29T12:40:53.373Z",
    "updatedAt": "2014-08-29T12:40:53.373Z"
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: view work package (on any project)

{
  "_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 label does not exist.

{
  "_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."
    }
  }
}

List labels by workspace

Returns a paginated collection of all labels, ordered by relevance for the given workspace: labels already used on work packages of the workspace come first, followed by the remaining labels. Within each group, labels are ordered by how often they are used overall and then by name.

id
integer

required path

ID of the workspace whose labels will be listed

Example:
1

filters
string

optional query

JSON specifying filter conditions. Currently supported filters are:

  • name: filters labels by name, with the operators ~ (contains), !~ (does not contain) and ** (all)

Example:
[{ "name": { "operator": "~", "values": ["bug"] } }]

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "self": {
            "href": "/api/v3/labels/1",
            "title": "Bug"
          }
        },
        "_type": "Label",
        "id": 1,
        "name": "Bug",
        "createdAt": "2014-08-29T12:40:53.373Z",
        "updatedAt": "2014-08-29T12:40:53.373Z"
      },
      {
        "_links": {
          "self": {
            "href": "/api/v3/labels/2",
            "title": "Frontend"
          }
        },
        "_type": "Label",
        "id": 2,
        "name": "Frontend",
        "createdAt": "2014-08-29T12:41:12.552Z",
        "updatedAt": "2014-08-29T12:41:12.552Z"
      },
      {
        "_links": {
          "self": {
            "href": "/api/v3/labels/3",
            "title": "Urgent"
          }
        },
        "_type": "Label",
        "id": 3,
        "name": "Urgent",
        "createdAt": "2014-08-29T12:42:03.128Z",
        "updatedAt": "2014-08-29T12:42:03.128Z"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/labels?filters=%5B%5D&offset=1&pageSize=20"
    },
    "jumpTo": {
      "href": "/api/v3/labels?filters=%5B%5D&offset=%7Boffset%7D&pageSize=20",
      "templated": true
    },
    "changeSize": {
      "href": "/api/v3/labels?filters=%5B%5D&offset=1&pageSize=%7Bsize%7D",
      "templated": true
    }
  },
  "_type": "Collection",
  "count": 3,
  "total": 3,
  "pageSize": 20,
  "offset": 1
}
LabelCollectionModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/OffsetPaginatedCollectionModel"
    },
    {
      "type": "object",
      "required": [
        "_links",
        "_embedded"
      ],
      "properties": {
        "_links": {
          "type": "object",
          "required": [
            "self"
          ],
          "properties": {
            "self": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "This label collection\n\n**Resource**: LabelCollectionModel",
                  "readOnly": true
                }
              ]
            }
          }
        },
        "_embedded": {
          "type": "object",
          "required": [
            "elements"
          ],
          "properties": {
            "elements": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/LabelModel"
              }
            }
          }
        }
      }
    }
  ]
}

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."
    }
  }
}

404

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

Required permission: view work packages (on given workspace)

Note: A client without sufficient permissions shall not be able to test for the existence of a workspace. That’s why a 404 is returned here, even if a 403 might be more appropriate.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified workspace 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."
    }
  }
}