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.

Markdown 

Preview Markdown document
/api/v3/render/markdown{?context}
  • Parameters
  • context
    string (optional) Example: /api/v3/work_packages/42

    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
  • Request
  • Headers
    Content-Type: text/plain
    Body
    Hello world! "This":http://example.com **is** markdown!
  • Response  200
  • Headers
    Content-Type: text/html
    Body
    <p>Hello world! <a href="http://example.com">This</a> <strong>is</strong> markdown!</p>
  • Response  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).

    Headers
    Content-Type: application/json
    Body
    {
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRenderContext",
  "message": "Could not render markdown string in the given context."
}
  • Response  415

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

    Headers
    Content-Type: application/json
    Body
    {
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected Content-Type to be 'text/plain' but got 'application/json'."
}

Plain Text 

Preview plain document
/api/v3/render/plain
  • Request
  • Headers
    Content-Type: text/plain
    Body
    Hello world! This *is* plain text!
  • Response  200
  • Headers
    Content-Type: text/html
    Body
    <p>Hello world! This *is* plain text!</p>
  • Response  415

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

    Headers
    Content-Type: application/json
    Body
    {
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected Content-Type to be 'text/plain' but got 'application/json'."
}