API: Types

Work package types represented in the system.

Types exist globally and are then activated for projects.

Linked Properties

Link Description Type Constraints Supported operations
self This type Type not null READ

Local Properties

Property Description Type Constraints Supported operations
id Type id Integer x > 0 READ
name Type name String READ
color The color used to represent this type Color READ
position Sort index of the type Integer READ
isDefault Is this type active by default in new projects? Boolean READ
isMilestone Do work packages of this type represent a milestone? Boolean READ
createdAt Time of creation DateTime READ
updatedAt Time of the most recent change to the user DateTime READ

Methods

List types available in a project

This endpoint lists the types that are available in a given project.

id
integer

required path

ID of the project whose types will be listed

Example:
1

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "self": {
            "href": "/api/v3/types/1"
          }
        },
        "_type": "Type",
        "color": "#ff0000",
        "createdAt": "2014-05-21T08:51:20.396Z",
        "id": 1,
        "isDefault": true,
        "isMilestone": false,
        "name": "Bug",
        "position": 1,
        "updatedAt": "2014-05-21T08:51:20.396Z"
      },
      {
        "_links": {
          "self": {
            "href": "/api/v3/types/2"
          }
        },
        "_type": "Type",
        "color": "#888",
        "createdAt": "2014-05-21T08:51:20.396Z",
        "id": 2,
        "isDefault": false,
        "isMilestone": false,
        "name": "Feature",
        "position": 2,
        "updatedAt": "2014-05-21T08:51:20.396Z"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/projects/11/types"
    }
  },
  "_type": "Collection",
  "count": 2,
  "total": 2
}
Types_by_ProjectModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/CollectionModel"
    },
    {
      "type": "object",
      "required": [
        "_links",
        "_embedded"
      ],
      "properties": {
        "_links": {
          "type": "object",
          "required": [
            "self"
          ],
          "properties": {
            "self": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "The types collection\n\n**Resource**: TypesCollection",
                  "readOnly": true
                }
              ]
            }
          }
        },
        "_embedded": {
          "type": "object",
          "properties": {
            "elements": {
              "type": "array",
              "readOnly": true,
              "items": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/TypeModel"
                  },
                  {
                    "description": "Collection of Types"
                  }
                ]
              }
            }
          }
        }
      }
    }
  ]
}

404

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

Required permission: view work packages or manage types (on given project)

Note: A client without sufficient permissions shall not be able to test for the existence of a project. 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 project 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."
    }
  }
}

List all types

No parameters

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "self": {
            "href": "/api/v3/types/1"
          }
        },
        "_type": "Type",
        "color": "#ff0000",
        "createdAt": "2014-05-21T08:51:20.396Z",
        "id": 1,
        "isDefault": true,
        "isMilestone": false,
        "name": "Bug",
        "position": 1,
        "updatedAt": "2014-05-21T08:51:20.396Z"
      },
      {
        "_links": {
          "self": {
            "href": "/api/v3/types/2"
          }
        },
        "_type": "Type",
        "color": "#888",
        "createdAt": "2014-05-21T08:51:20.396Z",
        "id": 2,
        "isDefault": false,
        "isMilestone": false,
        "name": "Feature",
        "position": 2,
        "updatedAt": "2014-05-21T08:51:20.396Z"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/types"
    }
  },
  "_type": "Collection",
  "count": 2,
  "total": 2
}
TypesModel
{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/types"
      }
    },
    "total": 2,
    "count": 2,
    "_type": "Collection",
    "_embedded": {
      "elements": [
        {
          "_links": {
            "self": {
              "href": "/api/v3/types/1"
            }
          },
          "_type": "Type",
          "id": 1,
          "name": "Bug",
          "color": "#ff0000",
          "position": 1,
          "isDefault": true,
          "isMilestone": false,
          "createdAt": "2014-05-21T08:51:20.429Z",
          "updatedAt": "2014-05-21T08:51:20.429Z"
        },
        {
          "_links": {
            "self": {
              "href": "/api/v3/types/2"
            }
          },
          "_type": "Type",
          "id": 2,
          "name": "Feature",
          "color": "#888",
          "position": 2,
          "isDefault": false,
          "isMilestone": false,
          "createdAt": "2014-05-21T08:51:20.429Z",
          "updatedAt": "2014-05-21T08:51:20.429Z"
        }
      ]
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: view work package or manage types (on any project)

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to see the types."
}
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 type

id
integer

required path

Type id

Example:
1

200

OK

{
  "_links": {
    "self": {
      "href": "/api/v3/types/1"
    }
  },
  "_type": "Type",
  "color": "#ff0000",
  "createdAt": "2014-05-21T08:51:20.396Z",
  "id": 1,
  "isDefault": true,
  "isMilestone": false,
  "name": "Bug",
  "position": 1,
  "updatedAt": "2014-05-21T08:51:20.396Z"
}
TypeModel
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Type id",
      "readOnly": true,
      "exclusiveMinimum": 0
    },
    "name": {
      "type": "string",
      "description": "Type name",
      "readOnly": true
    },
    "color": {
      "type": "string",
      "description": "The color used to represent this type",
      "readOnly": true
    },
    "position": {
      "type": "integer",
      "description": "Sort index of the type",
      "readOnly": true
    },
    "isDefault": {
      "type": "boolean",
      "description": "Is this type active by default in new projects?",
      "readOnly": true
    },
    "isMilestone": {
      "type": "boolean",
      "description": "Do work packages of this type represent a milestone?",
      "readOnly": true
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of creation",
      "readOnly": true
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of the most recent change to the user"
    },
    "_links": {
      "type": "object",
      "required": [
        "self"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This type\n\n**Resource**: Type",
              "readOnly": true
            }
          ]
        }
      }
    }
  },
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/types/1"
      }
    },
    "_type": "Type",
    "id": 1,
    "name": "Bug",
    "color": "#ff0000",
    "position": 1,
    "isDefault": true,
    "isMilestone": false,
    "createdAt": "2014-05-21T08:51:20.624Z",
    "updatedAt": "2014-05-21T08:51:20.624Z"
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: view work package or manage types (on any project)

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to see this type."
}
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."
    }
  }
}