API: Statuses

The statuses endpoints return collections or single entities of type Status. The following tables list the different properties of Status entities.

Linked Properties

Link Description Type Constraints Supported operations
self This status Status not null READ

Local Properties

Property Description Type Constraints Supported operations
id Status id Integer x > 0 READ
name Status name String READ
isClosed Indicates, whether work package of this status are considered closed Boolean READ
color A Hex-coded value of the color assigned to the status. String READ
isDefault True, if this status is the default status for new work packages Boolean READ
isReadonly Indicates, whether work package of this status are readonly Boolean READ
excludedFromTotals Indicates, whether work package of this status are excluded from totals of
Work, Remaining work, and % Complete in a hierarchy.		 Boolean READ
defaultDoneRatio The percentageDone being applied when changing to this status Integer 0 <= x <= 100 READ
position Sort index of the status Integer READ

Methods

List the collection of all statuses

Returns a collection of all work package statuses.

No parameters

200

OK

{
  "_type": "Collection",
  "count": 6,
  "total": 6,
  "_embedded": {
    "elements": [
      {
        "_type": "Status",
        "id": 1,
        "name": "New",
        "isClosed": false,
        "color": "#3997AD",
        "isDefault": true,
        "isReadonly": false,
        "excludedFromTotals": false,
        "defaultDoneRatio": 0,
        "position": 1,
        "_links": {
          "self": {
            "href": "/api/v3/statuses/1"
          }
        }
      },
      {
        "_type": "Status",
        "id": 3,
        "name": "Resolved",
        "isClosed": false,
        "color": "#93D2AE",
        "isDefault": false,
        "isReadonly": false,
        "excludedFromTotals": false,
        "defaultDoneRatio": 75,
        "position": 3,
        "_links": {
          "self": {
            "href": "/api/v3/statuses/3"
          }
        }
      },
      {
        "_type": "Status",
        "id": 4,
        "name": "Feedback",
        "isClosed": false,
        "color": "#A96FFE",
        "isDefault": false,
        "isReadonly": false,
        "excludedFromTotals": false,
        "defaultDoneRatio": 25,
        "position": 4,
        "_links": {
          "self": {
            "href": "/api/v3/statuses/4"
          }
        }
      },
      {
        "_type": "Status",
        "id": 5,
        "name": "Closed",
        "isClosed": true,
        "color": "#DF6DA1",
        "isDefault": false,
        "isReadonly": false,
        "excludedFromTotals": false,
        "defaultDoneRatio": 100,
        "position": 5,
        "_links": {
          "self": {
            "href": "/api/v3/statuses/5"
          }
        }
      },
      {
        "_type": "Status",
        "id": 6,
        "name": "Rejected",
        "isClosed": true,
        "color": "#D32937",
        "isDefault": false,
        "isReadonly": true,
        "excludedFromTotals": true,
        "defaultDoneRatio": 100,
        "position": 6,
        "_links": {
          "self": {
            "href": "/api/v3/statuses/6"
          }
        }
      },
      {
        "_type": "Status",
        "id": 2,
        "name": "In Progress",
        "isClosed": false,
        "color": "#3852C6",
        "isDefault": false,
        "isReadonly": false,
        "excludedFromTotals": false,
        "defaultDoneRatio": 50,
        "position": 3,
        "_links": {
          "self": {
            "href": "/api/v3/statuses/2"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/statuses"
    }
  }
}
StatusCollectionModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/CollectionModel"
    },
    {
      "type": "object",
      "required": [
        "_embedded"
      ],
      "properties": {
        "_embedded": {
          "type": "object",
          "required": [
            "elements"
          ],
          "properties": {
            "elements": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/StatusModel"
              }
            }
          }
        }
      }
    }
  ]
}

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 allowed to see the statuses."
}
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."
    }
  }
}

Get a work package status

Returns a work package status by its unique identifier.

id
integer

required path

Status id

Example:
1

200

OK

{
  "_type": "Status",
  "id": 13,
  "name": "Waiting for Darth-approval",
  "isClosed": false,
  "color": "#FE005D",
  "isDefault": false,
  "isReadonly": false,
  "excludedFromTotals": false,
  "defaultDoneRatio": 66,
  "position": 4,
  "_links": {
    "self": {
      "href": "/api/v3/statuses/13",
      "title": "Waiting for Darth-approval"
    }
  }
}
StatusModel
{
  "type": "object",
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "Status"
      ]
    },
    "id": {
      "type": "integer",
      "description": "Status id",
      "minimum": 1
    },
    "name": {
      "type": "string",
      "description": "Status name"
    },
    "isClosed": {
      "type": "boolean",
      "description": "Indicates, whether work package of this status are considered closed"
    },
    "color": {
      "type": "string",
      "format": "hex-code",
      "description": "The color of the status"
    },
    "isDefault": {
      "type": "boolean",
      "description": "True, if this status is the default status for new work packages"
    },
    "isReadonly": {
      "type": "boolean",
      "description": "Indicates, whether work package of this status are readonly"
    },
    "excludedFromTotals": {
      "type": "boolean",
      "description": "Indicates, whether work package of this status are excluded from totals of `Work`, `Remaining work`, and\n`% Complete` in a hierarchy."
    },
    "defaultDoneRatio": {
      "type": "integer",
      "description": "The percentageDone being applied when changing to this status",
      "minimum": 0,
      "maximum": 100
    },
    "position": {
      "type": "integer",
      "description": "Sort index of the status"
    },
    "_links": {
      "type": "object",
      "required": [
        "self"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This status\n\n**Resource**: Status"
            }
          ]
        }
      }
    }
  }
}

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 allowed to see this status."
}
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 status 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."
    }
  }
}