OpenProject Previewing API

openapi: 3.2.0
info:
  description: You're looking at the current **stable** documentation of the OpenProject APIv3.
  title: OpenProject API V3 (Stable) Previewing API
  version: '3'
servers:
- url: https://qa.openproject-edge.com
  description: Edge QA instance
- url: https://qa.openproject-stage.com
  description: Staging instance
- url: https://community.openproject.org
  description: Community instance
security:
- BasicAuth: []
tags:
- description: '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.'
  name: Previewing
paths:
  /api/v3/render/markdown:
    post:
      parameters:
      - description: '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
        in: query
        name: context
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            text/html:
              examples:
                response:
                  value: <p>Hello world! <a href="http://example.com">This</a> <strong>is</strong> markdown!</p>
              schema:
                $ref: '#/components/schemas/MarkdownModel'
          description: OK
          headers: {}
        '400':
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRenderContext
                    message: Could not render markdown string in the given context.
          description: '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: {}
        '415':
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:TypeNotSupported
                    message: Expected Content-Type to be 'text/plain' but got 'application/json'.
          description: Returned if the Content-Type indicated in the request is not `text/plain`.
          headers: {}
      tags:
      - Previewing
      description: ''
      operationId: Preview_Markdown_document
      summary: Preview Markdown document
  /api/v3/render/plain:
    post:
      responses:
        '200':
          content:
            text/html:
              examples:
                response:
                  value: '<p>Hello world! This *is* plain text!</p>

                    '
              schema:
                $ref: '#/components/schemas/Plain_TextModel'
          description: OK
          headers: {}
        '415':
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:TypeNotSupported
                    message: Expected Content-Type to be 'text/plain' but got 'application/json'.
          description: Returned if the Content-Type indicated in the request is not `text/plain`.
          headers: {}
      tags:
      - Previewing
      description: ''
      operationId: Preview_plain_document
      summary: Preview plain document
components:
  schemas:
    MarkdownModel:
      type: string
      format: html
      example: <p>Hello world! <a href="http://example.com">This</a> <strong>is</strong> markdown!</p>
    Plain_TextModel:
      type: string
      format: html
      example: <p>Hello world! This *is* plain text!</p>
    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.
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic