API: Previewing

Throughout OpenProject user input for many properties can be formatted using Markdown. Using the appropriate rendering endpoint it is possible to render custom formatted inputs into HTML and thus receive a preview of the rendered text.

The request to a rendering endpoint must always have a MIME-Type of text/plain. The request body is the actual string that shall be rendered as HTML string.

Methods

Preview markdown document

context
string

optional query

API-Link to the context in which the rendering occurs, for example a specific work package.

If left out only context-agnostic rendering takes place. Please note that OpenProject features markdown-extensions on top of the extensions GitHub Flavored Markdown (gfm) already provides that can only work given a context (e.g. display attached images).

Supported contexts:

  • /api/v3/work_packages/{id} - an existing work package

Example:
/api/v3/work_packages/42

200

OK

"<p>Hello world! <a href=\"http://example.com\">This</a> <strong>is</strong> markdown!</p>"
MarkdownModel
{
  "type": "string",
  "format": "html",
  "example": "<p>Hello world! <a href=\"http://example.com\">This</a> <strong>is</strong> markdown!</p>"
}

400

Returned if the context passed by the client is not valid (e.g. unknown).

Note that this response will also occur when the requesting user is not allowed to see the context resource (e.g. limited work package visibility).

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRenderContext",
  "message": "Could not render markdown string in the given context."
}
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."
    }
  }
}

415

Returned if the Content-Type indicated in the request is not text/plain.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected Content-Type to be 'text/plain' but got 'application/json'."
}
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."
    }
  }
}

Preview plain document

No parameters

200

OK

"<p>Hello world! This *is* plain text!</p>\n"
Plain_TextModel
{
  "type": "string",
  "format": "html",
  "example": "<p>Hello world! This *is* plain text!</p>"
}

415

Returned if the Content-Type indicated in the request is not text/plain.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected Content-Type to be 'text/plain' but got 'application/json'."
}
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."
    }
  }
}