API: Help texts

The help texts endpoints return collections or single entities of type HelpText. The following tables list the different properties of HelpText entities.

Linked Properties

Link	Description	Type	Constraints	Supported operations
self	This help text	HelpText	not null	READ
editText	Edit the help text entry	text/htm	Admin	READ

Local Properties

Property	Description	Type	Constraints	Supported operations
id	Help text id	Integer	x > 0	READ
attribute	Attribute name	String		READ
attributeCaption	Attribute caption	String		READ
helpText	Help text content	Formattable		READ

Methods

List help texts

List the complete collection of help texts.

No parameters

200

HelpTextCollectionModel

{
  "allOf": [
    {
      "$ref": "#/components/schemas/CollectionModel"
    },
    {
      "type": "object",
      "required": [
        "_links",
        "_embedded"
      ],
      "properties": {
        "_links": {
          "type": "object",
          "required": [
            "self"
          ],
          "properties": {
            "self": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "This help text collection\n\n**Resource**: HelpTextCollectionModel"
                }
              ]
            }
          }
        },
        "_embedded": {
          "type": "object",
          "required": [
            "elements"
          ],
          "properties": {
            "elements": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/HelpTextModel"
              }
            }
          }
        }
      }
    }
  ],
  "example": {
    "total": 2,
    "count": 2,
    "_type": "Collection",
    "_embedded": {
      "elements": [
        {
          "_type": "HelpText",
          "_links": {
            "self": {
              "href": "/api/v3/help_texts/1"
            }
          },
          "id": 1,
          "attribute": "id",
          "attributeCaption": "ID",
          "scope": "WorkPackage",
          "helpText": {
            "format": "markdown",
            "raw": "Help text for id attribute.",
            "html": "<p>Help text for id attribute.</p>"
          }
        },
        {
          "_type": "HelpText",
          "_links": {
            "self": {
              "href": "/api/v3/help_texts/2"
            }
          },
          "id": 2,
          "attribute": "status",
          "attributeCaption": "Status",
          "scope": "WorkPackage",
          "helpText": {
            "format": "markdown",
            "raw": "Help text for status attribute.",
            "html": "<p>Help text for status attribute.</p>"
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/api/v3/help_texts"
      }
    }
  }
}

Get help text

Fetches the help text from the given id.

id
integer

required path

Help text id

Example:
1

200

HelpTextModel

{
  "type": "object",
  "required": [
    "_type",
    "id",
    "attribute",
    "scope",
    "helpText",
    "_links"
  ],
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "HelpText"
      ]
    },
    "id": {
      "type": "integer",
      "format": "int64",
      "minimum": 1
    },
    "attribute": {
      "type": "string",
      "description": "The attribute the help text is assigned to."
    },
    "scope": {
      "type": "string",
      "enum": [
        "WorkPackage",
        "Project"
      ]
    },
    "helpText": {
      "$ref": "#/components/schemas/Formattable"
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "editText",
        "attachments",
        "addAttachment"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This help text resource.\n\n**Resource**: HelpText"
            }
          ]
        },
        "editText": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Edit the help text entry.\n\n**Resource**: text/html"
            }
          ]
        },
        "attachments": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The attachment collection of this help text.\n\n**Resource**: AttachmentCollection"
            }
          ]
        },
        "addAttachment": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Add an attachment to the help text."
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "HelpText",
    "id": 1,
    "attribute": "id",
    "scope": "WorkPackage",
    "helpText": {
      "format": "markdown",
      "raw": "Help text for id attribute.",
      "html": "<p>Help text for id attribute.</p>"
    },
    "_links": {
      "self": {
        "href": "/api/v3/help_texts/1"
      },
      "editText": {
        "href": "/admin/attribute_help_texts/1/edit",
        "type": "text/html"
      },
      "attachments": {
        "href": "/api/v3/help_texts/1/attachments"
      },
      "addAttachments": {
        "href": "/api/v3/help_texts/1/attachments",
        "method": "post"
      }
    }
  }
}

404

Returned if the help text 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."
    }
  }
}