---
openapi: 3.1.2
info:
  description: |-
    You're looking at the current **stable** documentation of the OpenProject APIv3. If you're interested in the current
    development version, please go to [github.com/opf](https://github.com/opf/openproject/tree/dev/docs/api/apiv3).

    ## Introduction

    The documentation for the APIv3 is written according to the [OpenAPI 3.1 Specification](https://swagger.io/specification/).
    You can either view the static version of this documentation on the [website](https://www.openproject.org/docs/api/introduction/)
    or the interactive version, rendered with [OpenAPI Explorer](https://github.com/Rhosys/openapi-explorer/blob/main/README.md),
    in your OpenProject installation under `/api/docs`.
    In the latter you can try out the various API endpoints directly interacting with our OpenProject data.
    Moreover you can access the specification source itself under `/api/v3/spec.json` and `/api/v3/spec.yml`
    (e.g. [here](https://community.openproject.org/api/v3/spec.yml)).

    The APIv3 is a hypermedia REST API, a shorthand for "Hypermedia As The Engine Of Application State" (HATEOAS).
    This means that each endpoint of this API will have links to other resources or actions defined in the resulting body.

    These related resources and actions for any given resource will be context sensitive. For example, only actions that the
    authenticated user can take are being rendered. This can be used to dynamically identify actions that the user might take for any
    given response.

    As an example, if you fetch a work package through the [Work Package endpoint](https://www.openproject.org/docs/api/endpoints/work-packages/), the `update` link will only
    be present when the user you authenticated has been granted a permission to update the work package in the assigned project.

    ## HAL+JSON

    HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API.
    Read more in the following specification: [https://tools.ietf.org/html/draft-kelly-json-hal-08](https://tools.ietf.org/html/draft-kelly-json-hal-08)

    **OpenProject API implementation of HAL+JSON format** enriches JSON and introduces a few meta properties:

    - `_type` - specifies the type of the resource (e.g.: WorkPackage, Project)
    - `_links` - contains all related resource and action links available for the resource
    - `_embedded` - contains all embedded objects

    HAL does not guarantee that embedded resources are embedded in their full representation, they might as well be
    partially represented (e.g. some properties can be left out).
    However in this API you have the guarantee that whenever a resource is **embedded**, it is embedded in its **full representation**.

    ## API response structure

    All API responses contain a single HAL+JSON object, even collections of objects are technically represented by
    a single HAL+JSON object that itself contains its members. More details on collections can be found
    in the [Collections Section](https://www.openproject.org/docs/api/collections/).

    ## Authentication

    The API supports the following authentication schemes:

    * Session-based authentication
    * API tokens
        * passed as Bearer token
        * passed via Basic auth
    * OAuth 2.0
        * using built-in authorization server
        * using an external authorization server (RFC 9068)

    Depending on the settings of the OpenProject instance many resources can be accessed without being authenticated.
    In case the instance requires authentication on all requests the client will receive an **HTTP 401** status code
    in response to any request.

    Otherwise unauthenticated clients have all the permissions of the anonymous user.

    ### Session-based authentication

    This means you have to login to OpenProject via the Web-Interface to be authenticated in the API.
    This method is well-suited for clients acting within the browser, like the Angular-Client built into OpenProject.

    Keep in mind that session-based authentication is only possible when accessing the API from the same origin. This
    is assured by checking the `Sec-Fetch-Site` HTTP header.

    ### API token as bearer token

    Users can authenticate towards the API v3 using an API token as a bearer token.

    For example:

    ```shell
    API_KEY=opapi-2519132cdf62dcf5a66fd96394672079f9e9cad1
    curl -H "Authorization: Bearer $API_KEY" https://community.openproject.org/api/v3/users/42
    ```

    Users can generate API tokens on their account page.

    ### API token through Basic Auth

    API tokens can also be used with basic auth, using the user name `apikey` (NOT your login) and the API token as the password.

    For example:

    ```shell
    API_KEY=opapi-2519132cdf62dcf5a66fd96394672079f9e9cad1
    curl -u apikey:$API_KEY https://community.openproject.org/api/v3/users/42
    ```

    ### OAuth 2.0 authentication

    OpenProject allows authentication and authorization with OAuth2 with *Authorization code flow*, as well as *Client credentials* operation modes.

    To get started, you first need to register an application in the OpenProject OAuth administration section of your installation.
    This will save an entry for your application with a client unique identifier (`client_id`) and an accompanying secret key (`client_secret`).

    You can then use one the following guides to perform the supported OAuth 2.0 flows:

    - [Authorization code flow](https://oauth.net/2/grant-types/authorization-code)

    - [Authorization code flow with PKCE](https://doorkeeper.gitbook.io/guides/ruby-on-rails/pkce-flow), recommended for clients unable to keep the client_secret confidential

    - [Client credentials](https://oauth.net/2/grant-types/client-credentials/) - Requires an application to be bound to an impersonating user for non-public access

    ### OAuth 2.0 using an external authorization server

    There is a possibility to use JSON Web Tokens (JWT) generated by an OIDC provider configured in OpenProject as a bearer token to do authenticated requests against the API.
    The following requirements must be met:

    - OIDC provider must be configured in OpenProject with **jwks_uri**
    - JWT must be signed using RSA algorithm
    - JWT **iss** claim must be equal to OIDC provider **issuer**
    - JWT **aud** claim must contain the OpenProject **client ID** used at the OIDC provider
    - JWT **scope** claim must include a valid scope to access the desired API (e.g. `api_v3` for APIv3)
    - JWT must be actual (neither expired or too early to be used)
    - JWT must be passed in Authorization header like: `Authorization: Bearer {jwt}`
    - User from **sub** claim must be linked to OpenProject before (e.g. by logging in), otherwise it will be not authenticated

    In more general terms, OpenProject should be compliant to [RFC 9068](https://www.rfc-editor.org/rfc/rfc9068) when validating access tokens.

    ### Why not username and password?

    The simplest way to do basic auth would be to use a user's username and password naturally.
    However, OpenProject already has supported API keys in the past for the API v2, though not through basic auth.

    Using **username and password** directly would have some advantages:

    * It is intuitive for the user who then just has to provide those just as they would when logging into OpenProject.

    * No extra logic for token management necessary.

    On the other hand using **API keys** has some advantages too, which is why we went for that:

    * If compromised while saved on an insecure client the user only has to regenerate the API key instead of changing their password, too.

    * They are naturally long and random which makes them invulnerable to dictionary attacks and harder to crack in general.

    Most importantly users may not actually have a password to begin with. Specifically when they have registered
    through an OpenID Connect provider.

    ## Cross-Origin Resource Sharing (CORS)

    By default, the OpenProject API is _not_ responding with any CORS headers.
    If you want to allow cross-domain AJAX calls against your OpenProject instance, you need to enable CORS headers being returned.

    Please see [our API settings documentation](https://www.openproject.org/docs/system-admin-guide/api-and-webhooks/) on
    how to selectively enable CORS.

    ## Allowed HTTP methods

    - `GET` - Get a single resource or collection of resources

    - `POST` - Create a new resource or perform

    - `PATCH` - Update a resource

    - `DELETE` - Delete a resource

    ## Compression

    Responses are compressed if requested by the client. Currently [gzip](https://www.gzip.org/) and [deflate](https://tools.ietf.org/html/rfc1951)
    are supported. The client signals the desired compression by setting the [`Accept-Encoding` header](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3).
    If no `Accept-Encoding` header is send, `Accept-Encoding: identity` is assumed which will result in the API responding uncompressed.
  title: OpenProject API V3 (Stable)
  version: '3'
servers:
- description: This server
  url: https://plm-ppp.thape.com.cn/
paths:
  "/api/v3":
    get:
      summary: View root
      operationId: view_root
      description: Returns the root resource, containing basic information about the
        server instance and a collection of useful links.
      tags:
      - Root
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/RootModel"
  "/api/v3/actions":
    get:
      parameters:
      - description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint.
          Currently supported filters are:

          + id: Returns only the action having the id or all actions except those having the id(s).
        example: '[{ "id": { "operator": "=", "values": ["memberships/create"] } }]'
        in: query
        name: filters
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          self:
                            href: "/api/v3/actions/work_packages/create"
                            title: Add work package
                        _type: Action
                        description: Creating a work package within a project including
                          the uploading of attachments. Some attributes might not
                          be selected, e.g version which requires a second permission
                        id: work_packages/create
                        modules:
                        - work_packages
                        name: Add work package
                      - _links:
                          self:
                            href: "/api/v3/actions/work_packages/assign_versions"
                            title: Assigning version
                        _type: Action
                        description: Assigning a work package to a version when creating/updating
                          a work package. Only principals having this permission can
                          assign a value to the version property of the work package
                          resource.
                        id: work_packages/assign_versions
                        modules:
                        - work_packages
                        - versions
                        name: Assign version
                    _links:
                      self:
                        href: "/api/v3/actions"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/List_actionsModel"
          description: OK
          headers: {}
      tags:
      - Actions & Capabilities
      description: |-
        Returns a collection of actions. The client can choose to filter the actions similar to how work packages are filtered.
        In addition to the provided filters, the server will reduce the result set to only contain actions, for which the requesting client
        has sufficient permissions.
      operationId: List_actions
      summary: List actions
  "/api/v3/actions/{id}":
    get:
      parameters:
      - description: action id which is the name of the action
        example: work_packages/create
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _links:
                      self:
                        href: "/api/v3/actions/work_packages/create"
                        title: Add work package
                    _type: Action
                    description: Creating a work package within a project including
                      the uploading of attachments. Some attributes might not be selected,
                      e.g version which requires a second permission
                    id: work_packages/create
                    modules:
                    - work_packages
                    name: Add work package
              schema:
                "$ref": "#/components/schemas/View_actionModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: Returned if the action does not exist.
          headers: {}
      tags:
      - Actions & Capabilities
      description: Returns an individual action.
      operationId: View_action
      summary: View action
  "/api/v3/activities/{id}":
    get:
      summary: Get an activity
      operationId: get_activity
      tags:
      - Activities
      description: Returns the requested activity resource identified by its unique
        id.
      parameters:
      - name: id
        description: Activity id
        in: path
        required: true
        schema:
          type: integer
        example: 1
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ActivityModel"
              examples:
                response:
                  "$ref": "#/components/examples/ActivityResponse"
    patch:
      summary: Update activity
      operationId: update_activity
      tags:
      - Activities
      description: Updates an activity's comment and, on success, returns the updated
        activity.
      parameters:
      - name: id
        description: Activity id
        in: path
        required: true
        schema:
          type: integer
        example: 1
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ActivityCommentWriteModel"
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ActivityModel"
              examples:
                response:
                  "$ref": "#/components/examples/ActivityResponse"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit journals
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to edit the comment of this journal
                      entry.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          description: Returned if the client tries to modify a read-only property.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyIsReadOnly
                    message: The ID of an activity can't be changed.
  "/api/v3/activities/{id}/attachments":
    get:
      summary: List attachments by activity
      operationId: list_activity_attachments
      tags:
      - Activities
      - Attachments
      description: List all attachments of a single activity.
      parameters:
      - name: id
        description: ID of the activity whose attachments will be listed
        in: path
        required: true
        schema:
          type: integer
        example: 1
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/Attachments_Model"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: "Returned if the activity does not exist or the client does
            not have sufficient permissions\nto see it.\n\n**Required permission:**
            \n- `view_work_packages`\n- for internal comments: `view_internal_comments`\n\n*Note:
            A client without sufficient permissions shall not be able to test for
            the existence of an activity.\nThat's why a 404 is returned here, even
            if a 403 might be more appropriate.*"
    post:
      summary: Add attachment to activity
      operationId: create_activity_attachment
      tags:
      - Activities
      - Attachments
      description: Adds an attachment to the specified activity.
      parameters:
      - name: id
        description: ID of the activity to receive the attachment
        in: path
        required: true
        schema:
          type: integer
        example: 1
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              "$ref": "#/components/schemas/FileUploadForm"
            encoding:
              metadata:
                contentType: application/json
              file:
                contentType: "*/*"
      responses:
        '201':
          description: Created
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/AttachmentModel"
        '400':
          description: Returned if the `metadata` part contains unparsable JSON.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
                    message: The request could not be parsed as JSON.
        '403':
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** view_work_packages or view_internal_comments (for internal comments)

            *Note that you will only receive this error, if you are at least allowed to see the activity*
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to add attachments to this activity.
        '404':
          description: |-
            Returned if the activity does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view_work_packages or view_internal_comments (for internal comments)

            *Note: A client without sufficient permissions shall not be able to test for the existence of an activity.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          description: |-
            Returned if the client tries to send an invalid attachment.
            Reasons are:

            * Omitting one of the required parts (`metadata` or `file`)

            * Sending metadata or file parts in an invalid format

            * Omitting the file name (`fileName` property of metadata part)

            * Sending a file that is too large
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: File is too large (maximum size is 5242880 Bytes).
  "/api/v3/activities/{id}/attachments/prepare":
    post:
      summary: Prepare a direct attachment upload for an activity
      operationId: prepare_activity_attachment_upload
      tags:
      - Activities
      - Attachments
      description: |-
        Prepares a direct upload of an attachment for the given activity (e.g. a work package
        comment), to be performed by the client without the file content passing through the
        OpenProject server. See `POST /api/v3/attachments/prepare` for a detailed description of the
        three-step flow this endpoint is the first step of.

        Unlike `POST /api/v3/attachments/prepare`, the resulting pending attachment is immediately
        associated with this activity as its container.
      parameters:
      - name: id
        description: ID of the activity to receive the attachment
        in: path
        required: true
        schema:
          type: integer
        example: 1
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - metadata
              properties:
                metadata:
                  type: string
                  contentMediaType: application/json
                  contentSchema:
                    "$ref": "#/components/schemas/AttachmentPrepareUploadWriteModel"
                  description: |-
                    A **single** part, named `metadata`, whose value is a *JSON-encoded string*
                    conforming to the schema referenced above (see the *Model* tab for its
                    properties) - it must **not** be split into separate `fileName`, `fileSize`, ...
                    form fields. No file content is sent with this request.
                  example: '{"fileName":"cat.png","fileSize":24,"contentType":"image/png"}'
            encoding:
              metadata:
                contentType: application/json
      responses:
        '201':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/AttachmentUploadModel"
        '400':
          description: |-
            Returned if the client sends a not understandable request. Reasons include:

            * Omitting the `metadata` part

            * sending unparsable JSON in the metadata part
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
                    message: The request could not be parsed as JSON.
        '403':
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** add_work_package_comments

            *Note that you will only receive this error, if you are at least allowed to see the activity*
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to add attachments to this activity.
        '404':
          description: |-
            Returned if the activity does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:**
            - `view_work_packages`
            - for internal comments: `view_internal_comments`

            *Note: A client without sufficient permissions shall not be able to test for the existence of an activity.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          description: |-
            Returned if the client tries to prepare an invalid attachment upload.
            Reasons are:

            * Omitting the file name (`fileName` property of metadata part)

            * Omitting the file size (`fileSize` property of metadata part)

            * The instance is not configured for direct uploads
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                direct uploads not available:
                  description: Returned if the OpenProject instance is not configured
                    for direct uploads.
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Direct file upload is not available due to a system configuration
                      issue. Please contact your administrator.
                missing file name:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: File can't be blank.
  "/api/v3/activities/{id}/emoji_reactions":
    get:
      summary: List emoji reactions by activity
      operationId: list_activity_emoji_reactions
      tags:
      - Activities
      - EmojiReactions
      description: List all emoji reactions of a single activity.
      parameters:
      - name: id
        description: ID of the activity whose emoji reactions will be listed
        in: path
        required: true
        schema:
          type: integer
        example: 1
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/EmojiReactions_Model"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the activity does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:**
            - `view_work_packages`
            - for internal comments: `view_internal_comments`

            *Note: A client without sufficient permissions shall not be able to test for the existence of an activity.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
    patch:
      summary: Toggle emoji reaction for an activity
      operationId: toggle_activity_emoji_reaction
      tags:
      - Activities
      - EmojiReactions
      description: |-
        Toggle an emoji reaction for a given activity. If the user has already reacted with the given emoji,
        the reaction will be removed. Otherwise, a new reaction will be created.

        **Note:** The response contains the complete collection of all emoji reactions for this activity.

        **Required permission:**
        - `add_work_package_comments`
        - for internal comments: `add_internal_comments`
      parameters:
      - name: id
        description: ID of the activity to toggle emoji reaction for
        in: path
        required: true
        schema:
          type: integer
        example: 1
      requestBody:
        required: true
        content:
          application/hal+json:
            schema:
              type: object
              required:
              - reaction
              properties:
                reaction:
                  type: string
                  description: The emoji reaction identifier
                  example: thumbs_up
                  enum:
                  - thumbs_up
                  - thumbs_down
                  - grinning_face_with_smiling_eyes
                  - confused_face
                  - heart
                  - party_popper
                  - rocket
                  - eyes
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/EmojiReactionModel"
        '400':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:BadRequest
                    message: 'Bad request: reaction does not have a valid value'
          description: Returned if the request is invalid. For example, if the reaction
            is not valid.
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: Returned if the client does not have sufficient permissions
            to toggle the emoji reaction for the activity.
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the activity does not exist or the client does not have sufficient permissions
            to see it.
  "/api/v3/attachments":
    post:
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              "$ref": "#/components/schemas/FileUploadForm"
            encoding:
              metadata:
                contentType: application/json
              file:
                contentType: "*/*"
      responses:
        '201':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/AttachmentModel"
          description: Created
        '400':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
                message: The request could not be parsed as JSON.
          description: Returned if the `metadata` part contains unparsable JSON.
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to delete this attachment.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** At least one permission in any project: edit work package, add work package, edit messages, edit wiki pages (plugins might extend this list)
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: File is too large (maximum size is 5242880 Bytes).
          description: |-
            Returned if the client tries to send an invalid attachment.
            Reasons are:

            * Omitting one of the required parts (`metadata` or `file`)

            * Sending metadata or file parts in an invalid format

            * Omitting the file name (`fileName` property of metadata part)

            * Sending a file that is too large
      tags:
      - Attachments
      description: |-
        Clients can create attachments without a container first and attach them later on.
        This is useful if the container does not exist at the time the attachment is uploaded.
        After the upload, the client can then claim such containerless attachments for any resource eligible (e.g. WorkPackage) on subsequent requests.
        The upload and the claiming *must* be done for the same user account. Attachments uploaded by another user cannot be claimed and
        once claimed for a resource, they cannot be claimed by another.

        The upload request must be of type `multipart/form-data` with exactly two parts.

        The first part *must* be called `metadata`. Its content type is expected to be `application/json`,
        the body *must* be a single JSON object, containing at least the `fileName` and optionally the attachments `description`.

        The second part *must* be called `file`, its content type *should* match the mime type of the file.
        The body *must* be the raw content of the file.
        Note that a `filename` *must* be indicated in the `Content-Disposition` of this part, although it will be ignored.
        Instead the `fileName` inside the JSON of the metadata part will be used.
      operationId: create_attachment
      summary: Create Attachment
  "/api/v3/attachments/prepare":
    post:
      summary: Prepare a direct attachment upload
      operationId: prepare_attachment_upload
      tags:
      - Attachments
      description: |-
        Prepares a **direct upload** of a file to OpenProject's attachment storage, bypassing the
        OpenProject server for the actual file transfer.

        ## Why this endpoint exists

        Attachments can always be created in one step by sending the raw file content together with
        the request, see `POST /api/v3/attachments` and the equivalent `.../attachments` endpoints of
        the various containers (work packages, wiki pages, meetings, ...). For large files or slow
        connections this means the file has to be transferred to the OpenProject server first, and
        then from there to the configured remote storage (e.g. an S3-compatible object store) - twice
        the traffic and twice the time.

        When OpenProject is configured to use a remote, S3-compatible storage for attachments,
        it can instead hand the client a short-lived, pre-signed upload
        instruction that allows the client to upload the file **directly** to that storage, without the
        OpenProject server ever being involved in the transfer. This is what this
        endpoint, and its per-container siblings such as
        `POST /api/v3/work_packages/{id}/attachments/prepare`, are used for.

        If direct uploads are not available (e.g. because attachments are stored on the local disk of
        the OpenProject server, or a remote storage without access-key credentials is used), this
        request fails with a `422` error. Clients should fall back to the regular, single-step upload
        in that case.

        ## The three-step flow

        1. **Prepare** (this request): the client tells the server the file name and size (and
           optionally its content type, description and a checksum) it intends to upload. The server
           creates a pending `Attachment` (`status: prepared`) without any file content yet and
           responds with an `AttachmentUpload` resource. That resource contains, among others:
            - `_links.addAttachment`: the direct upload instruction (`href`, `method` and `form_fields`)
              for the storage backend.
            - `_links.completeUpload`: the link to call once step 2 has finished.

        2. **Upload**: the client sends a `multipart/form-data` request exactly as instructed by
           `_links.addAttachment`, i.e. to the given `href`, using the given `method`, including every
           given `form_fields` entry as its own part (in the given order), and finally a `file` part
           carrying the raw file content as the *last* part of the request. This request goes directly
           to the storage backend, not to the OpenProject server.

        3. **Complete** (`GET` the href given in `_links.completeUpload`, i.e.
           `/api/v3/attachments/{id}/uploaded`): tells the OpenProject server that the direct upload has
           finished. The server verifies that the file is now present in the storage, and asynchronously
           finalizes the attachment (determining its definitive content type, matching it against the
           configured content type allowlist if any, running a virus scan if enabled, and creating
           activity/notifications for its container). The response is the regular `Attachment` resource.
           Until this step has completed, the pending attachment is not considered part of its
           container and will eventually be cleaned up if it is never completed.

        Only the user that prepared the upload can complete it; a pending upload that is never
        completed (e.g. because the client failed to perform step 2 or 3) is garbage collected after
        some time.

        ## Container vs. containerless uploads

        This endpoint (`/api/v3/attachments/prepare`) does not take a container - it prepares an
        attachment that is not yet attached to anything, e.g. because the containing resource (a new
        work package, for instance) does not exist yet. Such a containerless attachment can later be
        **claimed** by referencing its `id` while creating the eligible resource, exactly like
        containerless attachments created via `POST /api/v3/attachments`.

        Most containers that support attachments (e.g. work packages, wiki pages, meetings, forum
        messages, activity comments) additionally expose the very same operation scoped to an existing
        instance of themselves, e.g. `POST /api/v3/work_packages/{id}/attachments/prepare`. Using one
        of those instead immediately associates the resulting attachment with that container, and is
        subject to the same permission requirements as `POST .../attachments` on that container.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - metadata
              properties:
                metadata:
                  type: string
                  contentMediaType: application/json
                  contentSchema:
                    "$ref": "#/components/schemas/AttachmentPrepareUploadWriteModel"
                  description: |-
                    A **single** part, named `metadata`, whose value is a *JSON-encoded string*
                    conforming to the schema referenced above (see the *Model* tab for its
                    properties) - it must **not** be split into separate `fileName`, `fileSize`, ...
                    form fields. This is, unlike the regular attachment creation endpoints, the
                    *only* part of this request - no file content is sent here.
                  example: '{"fileName":"cat.png","fileSize":24,"contentType":"image/png"}'
            encoding:
              metadata:
                contentType: application/json
      responses:
        '201':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/AttachmentUploadModel"
        '400':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
                message: The request could not be parsed as JSON.
          description: |-
            Returned if the client sends a not understandable request. Reasons include:

            * Omitting the `metadata` part

            * Sending unparsable JSON in the `metadata` part
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to upload attachments.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** At least one permission in any project that allows creating
            attachments (e.g. edit work package, add work package, edit messages, edit wiki pages;
            plugins might extend this list)
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                direct uploads not available:
                  description: |-
                    Returned if the OpenProject instance is not configured for direct uploads, e.g.
                    because attachments are stored locally rather than in a remote, S3-compatible
                    storage with access-key credentials.
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Direct file upload is not available due to a system configuration
                      issue. Please contact your administrator.
                missing file name:
                  description: Returned if the `fileName` property of the metadata
                    part is missing.
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: File can't be blank.
                missing file size:
                  description: Returned if the `fileSize` property of the metadata
                    part is missing.
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Size can't be blank.
                content type not allowed:
                  description: |-
                    Returned if a specific `contentType` was given in the metadata part and it is not
                    part of the configured content type allowlist.
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: "'text/plain' is not allowed for upload."
          description: Returned if the client tries to prepare an invalid attachment
            upload.
  "/api/v3/attachments/{id}":
    delete:
      parameters:
      - description: Attachment id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: |-
            Returned if the attachment was deleted successfully.

            Note that the response body is empty as of now. In future versions of the API a body
            *might* be returned along with an appropriate HTTP status.
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to delete this attachment.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit permission for the container of the attachment or being the author for attachments without container

            *Note that you will only receive this error, if you are at least allowed to see the attachment.*
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified attachment does not exist.
          description: |-
            Returned if the attachment does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view permission for the container of the attachment or being the author for attachments without container

            *Note: A client without sufficient permissions shall not be able to test for the existence of an attachment.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
      tags:
      - Attachments
      description: Permanently deletes the specified attachment.
      operationId: delete_attachment
      summary: Delete attachment
    get:
      parameters:
      - description: Attachment id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/AttachmentModel"
          description: OK
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified attachment does not exist.
          description: |-
            Returned if the attachment does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view permission for the container of the attachment or being the author for attachments without container

            *Note: A client without sufficient permissions shall not be able to test for the existence of an attachment.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
      tags:
      - Attachments
      description: ''
      operationId: view_attachment
      summary: View attachment
  "/api/v3/attachments/{id}/uploaded":
    get:
      summary: Complete a direct attachment upload
      operationId: complete_attachment_upload
      tags:
      - Attachments
      description: |-
        This is the third and final step of the direct upload flow described at
        `POST /api/v3/attachments/prepare`. It is called by the client after it has successfully
        uploaded the file content directly to the storage backend, as instructed by the `addAttachment`
        link of the preceding `prepare` step.

        The server checks that the uploaded file is now present in the storage. If so, the attachment
        is scheduled to be finalized asynchronously (its definitive content type is determined, matched
        against the configured content type allowlist if any is configured, a virus scan is run if
        enabled, and the attachment's container is notified). The finalization may therefore not yet be
        reflected in the returned representation, in particular the `status` property might still read
        `prepared` for a brief moment, but will eventually change to `uploaded` (or the attachment
        removed, should the finalization fail, e.g. because the content type is not allowed).

        Calling this endpoint before the direct upload to the storage has actually finished (or if it
        failed) results in a `404` response.
      parameters:
      - name: id
        description: |-
          The `id` of the pending attachment, as returned by the `prepare` step (either in the
          top-level `id` property or, equivalently, in the `_links.completeUpload` link of the
          response).
        in: path
        required: true
        schema:
          type: integer
        example: 42
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/AttachmentModel"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if any of the following is true:

            * No pending, prepared upload with the given id exists (e.g. it was already completed, was
              never prepared, or does not belong to the current user)

            * the client does not have sufficient permissions to see the attachment

            * the file has not actually been uploaded to the storage backend yet (i.e. step 2 of the
              flow was skipped or has not finished successfully)

            *Note: A client without sufficient permissions shall not be able to test for the existence
            of an attachment. That's why a 404 is returned here, even if a 403 might be more
            appropriate.*
  "/api/v3/budgets/{id}":
    get:
      parameters:
      - description: Budget id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _links:
                      self:
                        href: "/api/v3/budgets/1"
                        title: Q3 2015
                    _type: Budget
                    id: 1
                    subject: Q3 2015
              schema:
                "$ref": "#/components/schemas/BudgetModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to see this budget.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** view work packages **or** view budgets (on the budgets project)
          headers: {}
      tags:
      - Budgets
      description: ''
      operationId: view_Budget
      summary: view Budget
  "/api/v3/capabilities":
    get:
      parameters:
      - description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint.

          + action: Get all capabilities of a certain action

          + principal: Get all capabilities of a principal

          + context: Get all capabilities within a context. Note that for a workspace context the client needs to
            provide `w{id}`, e.g. `w5` and for the global context a `g`.

            + **Deprecation**: The now deprecated context `p` for project still works, but must eventually be replaced
              with the `w` for the workspace context.
        example: '[{ "principal": { "operator": "=", "values": ["1"] } }]'
        in: query
        name: filters
        required: false
        schema:
          type: string
      - description: |-
          JSON specifying sort criteria.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported sorts are:

          + id: Sort by the capabilities id
        example: '[["id", "asc"]]'
        in: query
        name: sortBy
        required: false
        schema:
          default: '[["id", "asc"]]'
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          action:
                            href: "/api/v3/actions/work_packages/create"
                            title: Add work package
                          context:
                            href: "/api/v3/projects/123"
                            title: A project
                          principal:
                            href: "/api/v3/users/567"
                            title: Some user
                          self:
                            href: "/api/v3/capabilities/work_packages/create/w123-567"
                        _type: Capability
                        id: work_packages/create/w123-567
                      - _links:
                          action:
                            href: "/api/v3/actions/work_packages/assignee"
                          context:
                            href: "/api/v3/projects/123"
                            title: A project
                          principal:
                            href: "/api/v3/users/567"
                            title: Some user
                          self:
                            href: "/api/v3/capabilities/work_packages/assignee/w123-567"
                        _type: Capability
                        id: work_packages/assignee/w123-567
                      - _links:
                          action:
                            href: "/api/v3/actions/memberships/create"
                          context:
                            href: "/api/v3/portfolios/345"
                            title: A portfolio
                          principal:
                            href: "/api/v3/users/821"
                            title: Some user
                          self:
                            href: "/api/v3/capabilities/memberships/create/w345-821"
                            title: Create members
                        _type: Capability
                        id: memberships/create/w345-821
                      - _links:
                          context:
                            href: "/api/v3/capabilities/context/global"
                            title: Global
                          principal:
                            href: "/api/v3/users/567"
                            title: Some user
                          self:
                            href: "/api/v3/capabilities/users/delete/g-567"
                            title: Delete user
                        _type: Capability
                        id: users/delete/g-567
                    _links:
                      changeSize:
                        href: "/api/v3/capabilities?pageSize={size}"
                        templated: true
                      jumpTo:
                        href: "/api/v3/capabilities?offset={offset}"
                        templated: true
                      self:
                        href: "/api/v3/capabilities"
                    _type: Collection
                    count: 4
                    total: 4
              schema:
                "$ref": "#/components/schemas/List_capabilitiesModel"
          description: OK
          headers: {}
      tags:
      - Actions & Capabilities
      description: Returns a collection of actions assigned to a principal in a context.
        The client can choose to filter the actions similar to how work packages are
        filtered. In addition to the provided filters, the server will reduce the
        result set to only contain actions, for which the requesting client has sufficient
        permissions
      operationId: List_capabilities
      summary: List capabilities
  "/api/v3/capabilities/context/global":
    get:
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _links:
                      self:
                        href: "/api/v3/capabilities/context/global"
                    _type: CapabilityContext::Global
                    id: global
              schema:
                "$ref": "#/components/schemas/View_global_contextModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: Returned if the action does not exist.
          headers: {}
      tags:
      - Actions & Capabilities
      description: Returns the global capability context. This context is necessary
        to consistently link to a context even if the context is not a project.
      operationId: View_global_context
      summary: View global context
  "/api/v3/capabilities/{id}":
    get:
      parameters:
      - description: capability id
        example: work_packages/create/p123-567
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _links:
                      action:
                        href: "/api/v3/actions/work_packages/create"
                        title: Add work package
                      context:
                        href: "/api/v3/projects/123"
                        title: A project
                      principal:
                        href: "/api/v3/users/567"
                        title: Some user
                      self:
                        href: "/api/v3/capabilities/work_packages/create/w123-567"
                    _type: Capability
                    id: work_packages/create/p123-567
              schema:
                "$ref": "#/components/schemas/View_capabilitiesModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: Returned if the capability does not exist.
          headers: {}
      tags:
      - Actions & Capabilities
      description: ''
      operationId: View_capabilities
      summary: View capabilities
  "/api/v3/categories/{id}":
    get:
      parameters:
      - description: Category id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _links:
                      defaultAssignee:
                        href: "/api/v3/users/42"
                        title: John Sheppard
                      project:
                        href: "/api/v3/projects/11"
                        title: Example project
                      self:
                        href: "/api/v3/categories/10"
                        title: Category with assignee
                    _type: Category
                    id: 10
                    name: Foo
              schema:
                "$ref": "#/components/schemas/CategoryModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified category does not exist.
          description: |-
            Returned if the category does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view project (defining the category)

            *Note: A client without sufficient permissions shall not be able to test for the existence of
            a category. That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
      tags:
      - Categories
      description: ''
      operationId: View_Category
      summary: View Category
  "/api/v3/configuration":
    get:
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _type: Configuration
                    _links:
                      self:
                        href: "/api/v3/configuration"
                      userPreferences:
                        href: "/api/v3/my_preferences"
                    maximumAttachmentFileSize: 5242880
                    hostName: example.com:8080
                    perPageOptions:
                    - 1
                    - 10
                    - 100
                    durationFormat: hours_only
                    activeFeatureFlags:
                    - aFeatureFlag
                    - anotherFeatureFlag
              schema:
                "$ref": "#/components/schemas/ConfigurationModel"
          description: OK
          headers: {}
      tags:
      - Configuration
      description: ''
      operationId: View_configuration
      summary: View configuration
  "/api/v3/custom_actions/{id}":
    get:
      summary: Get a custom action
      tags:
      - Custom actions
      description: Retrieves a custom action by id.
      operationId: get_custom_action
      parameters:
      - name: id
        description: The id of the custom action to fetch
        in: path
        required: true
        schema:
          type: integer
        example: 42
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/CustomActionModel"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit work packages in any project
        '404':
          description: Returned if the custom action does not exist.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
  "/api/v3/custom_actions/{id}/execute":
    post:
      parameters:
      - description: The id of the custom action to execute
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/WorkPackageModel"
          description: OK
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit work packages - Additional permissions might be required based on the custom action.
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: Returned if the custom action does not exist.
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '409':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:UpdateConflict
                    message: Couldn't update the resource because of conflicting modifications.
          description: Returned if the client provided an outdated lockVersion or
            no lockVersion at all.
          headers: {}
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _embedded:
                      details:
                        attribute: lag
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Lag must be a number greater than or equal to 0
          description: Returned if the custom action was not executed successfully
            e.g. when a constraint on a work package property was violated.
          headers: {}
      tags:
      - Custom actions
      description: |-
        A POST to this endpoint executes the custom action on the work package provided in the payload. The altered work package will be returned. In order to avoid executing
         the custom action unbeknown to a change that has already taken place, the client has to provide the work package's current lockVersion.
      operationId: Execute_custom_action
      requestBody:
        content:
          application/json:
            schema:
              example:
                _links:
                  workPackage:
                    href: "/api/v3/work_packages/42"
                lockVersion: '3'
              properties:
                _links:
                  properties:
                    workPackage:
                      properties:
                        href:
                          type: string
                      type: object
                  type: object
                lockVersion:
                  type: string
              type: object
      summary: Execute custom action
  "/api/v3/custom_fields/{id}":
    get:
      summary: Get custom field
      operationId: get_custom_field
      description: Retrieves the custom field with the given ID.
      tags:
      - Custom Fields
      parameters:
      - name: id
        description: The custom field's unique identifier
        in: path
        example: 42
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/CustomFieldModel"
        '403':
          description: Returned if the user is not logged in.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
        '404':
          description: Returned if the custom field does not exist or the user lacks
            the permission to view it.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
  "/api/v3/custom_fields/{id}/items":
    get:
      summary: Get the custom field hierarchy items
      operationId: get_custom_field_items
      description: |-
        Retrieves the hierarchy of custom fields.

        The hierarchy is a tree structure of hierarchy items. It is represented as a flat list of items, where each item
        has a reference to its parent and children. The list is ordered in a depth-first manner. The first item is the
        requested parent. If parent was unset, the root item is returned as first element.

        Passing the `depth` query parameter allows to limit the depth of the hierarchy. If the depth is unset, the full
        hierarchy tree is returned. If the depth is set to `0`, only the requested parent is returned. Any other positive
        integer will return the number of children levels specified by this value.

        This endpoint only returns, if the custom field is of type `hierarchy`.
      tags:
      - Custom Fields
      parameters:
      - name: id
        description: The custom field's unique identifier
        in: path
        example: 42
        required: true
        schema:
          type: integer
      - name: parent
        description: The identifier of the parent hierarchy item
        in: query
        example: 1337
        required: false
        schema:
          type: integer
      - name: depth
        description: The level of hierarchy depth
        in: query
        example: 1
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/HierarchyItemCollectionModel"
              examples:
                simple response:
                  "$ref": "#/components/examples/HierarchyItemCollectionResponse"
                filtered response:
                  "$ref": "#/components/examples/HierarchyItemCollectionFilteredResponse"
        '403':
          description: Returned if the user is not logged in.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
        '404':
          description: Returned if the custom field does not exist or the user lacks
            the permission to view it.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
        '422':
          description: Returned if the custom field is not of type hierarchy.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:UnprocessableContent
                    message: The requested custom field resource is of wrong type.
  "/api/v3/custom_field_items/{id}":
    get:
      summary: Get a custom field hierarchy item
      operationId: get_custom_field_item
      description: Retrieves a single custom field item specified by its unique identifier.
      tags:
      - Custom Fields
      parameters:
      - name: id
        description: The custom field item's unique identifier
        in: path
        example: 42
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/HierarchyItemReadModel"
              examples:
                simple response:
                  "$ref": "#/components/examples/HierarchyItemResponse"
        '403':
          description: Returned if the user is not logged in.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
        '404':
          description: |-
            Returned if the custom field item does not exist or the user lacks permission to see it.

            The permission required to view the item depends on the custom field it belongs to.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
  "/api/v3/custom_field_items/{id}/branch":
    get:
      summary: Get a custom field hierarchy item's branch
      operationId: get_custom_field_item_branch
      description: |-
        Retrieves the branch of a single custom field item specified by its unique identifier.

        A branch is list of all ancestors, starting with the root item and finishing with the item itself.
      tags:
      - Custom Fields
      parameters:
      - name: id
        description: The custom field item's unique identifier
        in: path
        example: 42
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/HierarchyItemCollectionModel"
              examples:
                simple response:
                  "$ref": "#/components/examples/HierarchyItemCollectionResponse"
        '403':
          description: Returned if the user is not logged in.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
        '404':
          description: Returned if the custom field does not exist or the user lacks
            permission to view it.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
        '422':
          description: Returned if the custom field is not of type hierarchy.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:UnprocessableContent
                    message: The requested custom field resource is of wrong type.
  "/api/v3/custom_options/{id}":
    get:
      parameters:
      - description: The custom option's identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _links:
                      self:
                        href: "/api/v3/custom_options/1"
                    _type: CustomOption
                    value: Foo
              schema:
                "$ref": "#/components/schemas/CustomOptionModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the custom option does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work package in any project the custom option's custom field is active in.
          headers: {}
      tags:
      - Custom Options
      description: ''
      operationId: View_Custom_Option
      summary: View Custom Option
  "/api/v3/days/non_working":
    get:
      summary: Lists all non working days
      operationId: list_non_working_days
      tags:
      - Work Schedule
      description: |-
        Lists all one-time non working days, such as holidays.
        It does not lists the non working weekdays, such as each Saturday, Sunday.
        For listing the weekends, the `/api/v3/days` endpoint should be used.

        All days from current year are returned by default.
      parameters:
      - name: filters
        in: query
        description: |-
          JSON specifying filter conditions.

          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/)
          endpoint. Currently supported filters are:

          + date: the inclusive date interval to scope days to look up. When
            unspecified, default is from the beginning to the end of current year.

            Example: `{ "date": { "operator": "<>d", "values": ["2022-05-02","2022-05-26"] } }`
            would return days between May 5 and May 26 2022, inclusive.
        example: '[{ "date": { "operator": "<>d", "values": ["2022-05-02","2022-05-26"]
          } }]'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/NonWorkingDayCollectionModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
    post:
      summary: Creates a non-working day (NOT IMPLEMENTED)
      operationId: create_non_working_day
      tags:
      - Work Schedule
      description: |-
        **(NOT IMPLEMENTED)**
        Marks a day as being a non-working day.

        Note: creating a non-working day will not affect the start and finish dates
        of work packages but will affect their duration.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/NonWorkingDayModel"
            example:
              _type: NonWorkingDay
              date: '2022-12-25'
              name: Christmas
      responses:
        '201':
          description: Non-working day created.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/NonWorkingDayModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          description: Returned if the client does not have sufficient permissions.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
                message: You are not authorized to access this resource.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
  "/api/v3/days/non_working/{date}":
    get:
      summary: View a non-working day
      operationId: view_non_working_day
      tags:
      - Work Schedule
      description: Returns the non-working day information for a given date.
      parameters:
      - name: date
        in: path
        required: true
        description: The date of the non-working day to view in ISO 8601 format.
        schema:
          type: string
          format: date
        example: '2022-05-06'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/NonWorkingDayModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '404':
          description: Returned if the given date is not a non-working day.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
    patch:
      summary: Update a non-working day attributes (NOT IMPLEMENTED)
      operationId: update_non_working_day
      tags:
      - Work Schedule
      description: |-
        **(NOT IMPLEMENTED)**
        Update the non-working day information for a given date.
      parameters:
      - name: date
        in: path
        required: true
        description: The date of the non-working day to view in ISO 8601 format.
        schema:
          type: string
          format: date
        example: '2022-05-06'
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/NonWorkingDayModel"
            example:
              _type: NonWorkingDay
              date: '2022-05-01'
              name: Labour day
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/NonWorkingDayModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '404':
          description: Returned if the given date is not a non-working day.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
    delete:
      summary: Removes a non-working day (NOT IMPLEMENTED)
      operationId: delete_non_working_day
      tags:
      - Work Schedule
      description: |-
        **(NOT IMPLEMENTED)**
        Removes the non-working day at the given date.

        Note: deleting a non-working day will not affect the start and finish dates
        of work packages but will affect their duration.
      parameters:
      - name: date
        in: path
        required: true
        description: The date of the non-working day to view in ISO 8601 format.
        schema:
          type: string
          format: date
        example: '2022-05-06'
      responses:
        '204':
          description: |-
            No Content.

            The operation succeeded.
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '404':
          description: Returned if the given date is not a non-working day.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
  "/api/v3/days/week":
    get:
      summary: Lists week days
      operationId: list_week_days
      tags:
      - Work Schedule
      description: Lists week days with work schedule information.
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/WeekDayCollectionModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
    patch:
      summary: Update week days (NOT IMPLEMENTED)
      operationId: update_week_days
      tags:
      - Work Schedule
      description: |-
        **(NOT IMPLEMENTED)**
        Update multiple week days with work schedule information.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WeekDayCollectionWriteModel"
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/WeekDayCollectionModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '404':
          description: Returned if a week day resource can not be found.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
                message: The requested resource could not be found.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
  "/api/v3/days/week/{day}":
    get:
      summary: View a week day
      operationId: view_week_day
      tags:
      - Work Schedule
      description: View a week day and its attributes.
      parameters:
      - name: day
        in: path
        required: true
        description: The week day from 1 to 7. 1 is Monday. 7 is Sunday.
        schema:
          type: integer
          minimum: 1
          maximum: 7
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/WeekDayModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '404':
          description: Returned if the day is out of the 1-7 range.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
    patch:
      summary: Update a week day attributes (NOT IMPLEMENTED)
      operationId: update_week_day
      description: |-
        **(NOT IMPLEMENTED)**
        Makes a week day a working or non-working day.

        Note: changing a week day working attribute will not affect the start and
        finish dates of work packages but will affect their duration attribute.
      tags:
      - Work Schedule
      parameters:
      - name: day
        in: path
        required: true
        description: The week day from 1 to 7. 1 is Monday. 7 is Sunday.
        schema:
          type: integer
          minimum: 1
          maximum: 7
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WeekDayWriteModel"
            example:
              _type: WeekDay
              working: false
      responses:
        '200':
          description: |-
            Update succeeded.

            Response will include the week day with updated attributes.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/WeekDayModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          description: Returned if the client does not have sufficient permissions.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
                message: You are not authorized to access this resource.
        '404':
          description: Returned if the day is out of the 1-7 range.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
                message: The requested resource could not be found.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
  "/api/v3/days":
    get:
      summary: Lists days
      operationId: list_days
      tags:
      - Work Schedule
      description: |-
        Lists days information for a given date interval.

        All days from the beginning of current month to the end of following month
        are returned by default.
      parameters:
      - name: filters
        in: query
        description: |-
          JSON specifying filter conditions.

          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/)
          endpoint. Currently supported filters are:

          + date: the inclusive date interval to scope days to look up. When
            unspecified, default is from the beginning of current month to the end
            of following month.

            Example: `{ "date": { "operator": "<>d", "values": ["2022-05-02","2022-05-26"] } }`
            would return days between May 5 and May 26 2022, inclusive.

          + working: when `true`, returns only the working days. When `false`,
            returns only the non-working days (weekend days and non-working days).
            When unspecified, returns both working and non-working days.

            Example: `{ "working": { "operator": "=", "values": ["t"] } }`
            would exclude non-working days from the response.
        example: '[{ "date": { "operator": "<>d", "values": ["2022-05-02","2022-05-26"]
          } }, { "working": { "operator": "=", "values": ["f"] } }]'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/DayCollectionModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
  "/api/v3/days/{date}":
    get:
      summary: View day
      operationId: view_day
      tags:
      - Work Schedule
      description: View the day information for a given date.
      parameters:
      - name: date
        in: path
        required: true
        description: The date of the non-working day to view in ISO 8601 format.
        schema:
          type: string
          format: date
        example: '2022-05-06'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/DayModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
  "/api/v3/documents":
    get:
      parameters:
      - description: Page number inside the requested collection.
        example: 25
        in: query
        name: offset
        required: false
        schema:
          default: 1
          type: integer
      - description: Number of elements to display per page.
        example: 25
        in: query
        name: pageSize
        required: false
        schema:
          type: integer
      - description: |-
          JSON specifying sort criteria.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported sorts are:

          + id: Sort by primary key

          + created_at: Sort by document creation datetime
        example: '[["created_at", "asc"]]'
        in: query
        name: sortBy
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          addAttachment:
                            href: "/api/v3/documents/1/attachments"
                            method: post
                          attachments:
                            href: "/api/v3/documents/1/attachments"
                          project:
                            href: "/api/v3/projects/19"
                            title: Some project
                          self:
                            href: "/api/v3/documents/1"
                            title: Some document
                        _type: Document
                        createdAt: '2018-12-10T20:53:39.184Z'
                        description:
                          format: markdown
                          html: "<p>Videlicet deserunt aequitas cognatus. Concedo
                            quia est quia pariatur vorago vallum. Calco autem atavus
                            accusamus conscendo cornu ulterius. Tam patria ago consectetur
                            ventito sustineo nihil caecus. Supra officiis eos velociter
                            somniculosus tonsor qui. Suffragium aduro arguo angustus
                            cogito quia tolero vulnus. Supplanto sortitus cresco apud
                            vestrum qui.</p>"
                          raw: Videlicet deserunt aequitas cognatus. Concedo quia
                            est quia pariatur vorago vallum. Calco autem atavus accusamus
                            conscendo cornu ulterius. Tam patria ago consectetur ventito
                            sustineo nihil caecus. Supra officiis eos velociter somniculosus
                            tonsor qui. Suffragium aduro arguo angustus cogito quia
                            tolero vulnus. Supplanto sortitus cresco apud vestrum
                            qui.
                        id: 1
                        title: Some other document
                      - _links:
                          addAttachment:
                            href: "/api/v3/documents/2/attachments"
                            method: post
                          attachments:
                            href: "/api/v3/documents/2/attachments"
                          project:
                            href: "/api/v3/projects/29"
                            title: Some other project
                          self:
                            href: "/api/v3/documents/2"
                            title: Some other document
                        _type: Document
                        createdAt: '2018-12-10T20:55:54.049Z'
                        description:
                          format: markdown
                          html: "<p>Videlicet deserunt aequitas cognatus. Concedo
                            quia est quia pariatur vorago vallum. Calco autem atavus
                            accusamus conscendo cornu ulterius. Tam patria ago consectetur
                            ventito sustineo nihil caecus. Supra officiis eos velociter
                            somniculosus tonsor qui. Suffragium aduro arguo angustus
                            cogito quia tolero vulnus. Supplanto sortitus cresco apud
                            vestrum qui.</p>"
                          raw: Videlicet deserunt aequitas cognatus. Concedo quia
                            est quia pariatur vorago vallum. Calco autem atavus accusamus
                            conscendo cornu ulterius. Tam patria ago consectetur ventito
                            sustineo nihil caecus. Supra officiis eos velociter somniculosus
                            tonsor qui. Suffragium aduro arguo angustus cogito quia
                            tolero vulnus. Supplanto sortitus cresco apud vestrum
                            qui.
                        id: 2
                        title: Some other document
                    _links:
                      changeSize:
                        href: "/api/v3/documents?offset=1&pageSize=%7Bsize%7D"
                        templated: true
                      jumpTo:
                        href: "/api/v3/documents?offset=%7Boffset%7D&pageSize=30"
                        templated: true
                      self:
                        href: "/api/v3/documents?offset=1&pageSize=30"
                    _type: Collection
                    count: 2
                    offset: 1
                    pageSize: 30
                    total: 2
              schema:
                "$ref": "#/components/schemas/DocumentsModel"
          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:InvalidQuery
                    message:
                    - Filters Invalid filter does not exist.
          description: Returned if the client sends invalid request parameters e.g.
            filters
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to view this resource.
          description: Returned if the client is not logged in and login is required.
          headers: {}
      tags:
      - Documents
      description: The documents returned depend on the provided parameters and also
        on the requesting user's permissions.
      operationId: List_Documents
      summary: List Documents
  "/api/v3/documents/{id}":
    get:
      parameters:
      - description: Document id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      attachments:
                        _embedded...:
                          elements: []
                        _links:
                          self:
                            href: "/api/v3/documents/1/attachments"
                        _type: Collection
                        count: 2
                        total: 2
                      project:
                        _type: Project...
                    _links:
                      addAttachment:
                        href: "/api/v3/documents/1/attachments"
                        method: post
                      attachments:
                        href: "/api/v3/documents/1/attachments"
                      project:
                        href: "/api/v3/projects/19"
                        title: Some project
                      self:
                        href: "/api/v3/documents/1"
                        title: Some document
                    _type: Document
                    createdAt: '2018-12-10T20:53:39.698Z'
                    description:
                      format: markdown
                      html: "<p>Videlicet deserunt aequitas cognatus. Concedo quia
                        est quia pariatur vorago vallum. Calco autem atavus accusamus
                        conscendo cornu ulterius. Tam patria ago consectetur ventito
                        sustineo nihil caecus. Supra officiis eos velociter somniculosus
                        tonsor qui. Suffragium aduro arguo angustus cogito quia tolero
                        vulnus. Supplanto sortitus cresco apud vestrum qui.</p>"
                      raw: Videlicet deserunt aequitas cognatus. Concedo quia est
                        quia pariatur vorago vallum. Calco autem atavus accusamus
                        conscendo cornu ulterius. Tam patria ago consectetur ventito
                        sustineo nihil caecus. Supra officiis eos velociter somniculosus
                        tonsor qui. Suffragium aduro arguo angustus cogito quia tolero
                        vulnus. Supplanto sortitus cresco apud vestrum qui.
                    id: 1
                    title: Some other document
              schema:
                "$ref": "#/components/schemas/DocumentModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the document does not exist or if the user does not have permission to view it.

            **Required permission** `view documents` in the project the document belongs to
          headers: {}
      tags:
      - Documents
      description: ''
      operationId: View_document
      summary: View document
    patch:
      parameters:
      - description: Document id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: The title of the document
                description:
                  type: object
                  properties:
                    raw:
                      type: string
                      description: The raw markdown content
            examples:
              request:
                value:
                  title: Updated document title
                  description:
                    raw: Updated description content
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      attachments:
                        _embedded...:
                          elements: []
                        _links:
                          self:
                            href: "/api/v3/documents/1/attachments"
                        _type: Collection
                        count: 2
                        total: 2
                      project:
                        _type: Project...
                    _links:
                      addAttachment:
                        href: "/api/v3/documents/1/attachments"
                        method: post
                      attachments:
                        href: "/api/v3/documents/1/attachments"
                      project:
                        href: "/api/v3/projects/19"
                        title: Some project
                      self:
                        href: "/api/v3/documents/1"
                        title: Updated document title
                    _type: Document
                    createdAt: '2018-12-10T20:53:39.698Z'
                    description:
                      format: markdown
                      html: "<p>Updated description content</p>"
                      raw: Updated description content
                    id: 1
                    title: Updated document title
              schema:
                "$ref": "#/components/schemas/DocumentModel"
          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:BadRequest
                    message: The request body was invalid.
          description: Returned if the request body is invalid.
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the user does not have permission to edit the document.

            **Required permission** `manage documents` in the project the document belongs to
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the document does not exist or if the user does not have permission to view it.

            **Required permission** `view documents` in the project the document belongs to
          headers: {}
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Title can't be blank.
                    _embedded:
                      details:
                        attribute: title
          description: Returned if the request body contains validation errors.
          headers: {}
      tags:
      - Documents
      description: Updates a document's attributes.
      operationId: Update_document
      summary: Update document
  "/api/v3/file_links/{id}":
    get:
      summary: Gets a file link.
      operationId: view_file_link
      tags:
      - File links
      description: Gets a single file link resource of a work package.
      parameters:
      - name: id
        description: File link id
        in: path
        required: true
        schema:
          type: integer
        example: 42
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/FileLinkReadModel"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work package, view file links
    delete:
      summary: Removes a file link.
      operationId: delete_file_link
      tags:
      - File links
      description: |-
        Removes a file link on a work package.

        The request contains only the file link identifier as a path parameter. No request body is needed.
      parameters:
      - name: id
        description: File link id
        in: path
        required: true
        schema:
          type: integer
        example: 42
      responses:
        '200':
          description: OK
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage file links

            *Note that you will only receive this error, if you are at least allowed to see the corresponding work package.*
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the work package or the file link does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view work package, view file links
  "/api/v3/file_links/{id}/open":
    get:
      summary: Creates an opening uri of the linked file.
      operationId: open_file_link
      tags:
      - File links
      description: |-
        Creates a uri to open the origin file linked by the given file link. This uri depends on the storage type and
        is always located on the origin storage itself.
      parameters:
      - name: id
        description: File link id
        in: path
        required: true
        schema:
          type: integer
        example: 42
      - name: location
        description: Boolean flag indicating, if the file should be opened directly
          or rather the directory location.
        in: query
        required: false
        schema:
          type: boolean
        example: true
      responses:
        '303':
          headers:
            Location:
              schema:
                type: string
                format: uri
          description: |-
            Returned if the request was successful. In the `Location` header is the uri where the client can open the origin
            file on the storage.
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work package, view file links
  "/api/v3/file_links/{id}/download":
    get:
      summary: Creates a download uri of the linked file.
      operationId: download_file_link
      tags:
      - File links
      description: |-
        Creates a uri to download the origin file linked by the given file link. This uri depends on the storage type and
        is always located on the origin storage itself.
      parameters:
      - name: id
        description: File link id
        in: path
        required: true
        schema:
          type: integer
        example: 42
      responses:
        '303':
          headers:
            Location:
              schema:
                type: string
                format: uri
          description: |-
            Returned if the request was successful. In the `Location` header is the uri where the client can download the
            origin file from the storage.
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work package, view file links
  "/api/v3/grids":
    get:
      summary: List grids
      tags:
      - Grids
      description: |-
        Lists all grids matching the provided filters and being part of the selected query page. The grids returned will
        also depend on the permissions of the requesting user.
      operationId: list_grids
      parameters:
      - name: offset
        schema:
          type: integer
          default: 1
        description: Page number inside the requested collection.
        in: query
        required: false
        example: 25
      - name: pageSize
        schema:
          type: integer
          default: 30
        description: Number of elements to display per page.
        in: query
        required: false
        example: 25
      - name: filters
        schema:
          type: string
        description: |-
          JSON specifying filter conditions. Accepts the same format as returned by
          the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported filters
          are:

          - page: Filter grid by work package
        in: query
        required: false
        example: '[{ "page": { "operator": "=", "values": ["/my/page"] } }]'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/GridCollectionModel"
              examples:
                Simple grid collection:
                  "$ref": "#/components/examples/GridSimpleCollectionResponse"
        '400':
          "$ref": "#/components/responses/InvalidQuery"
        '403':
          description: Returned if the client is not logged in and login is required.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to view this resource.
    post:
      summary: Create a grid
      operationId: create_grid
      tags:
      - Grids
      description: |-
        Creates a new grid applying the attributes provided in the body. The constraints applied to the grid depend on the
        page the grid is placed in which is why the create form endpoint should be used to be guided when wanting to
        create a grid.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/GridWriteModel"
            examples:
              Simple grid creation:
                "$ref": "#/components/examples/GridSimplePatchModel"
      responses:
        '201':
          description: Created
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/GridReadModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** Depends on the page the grid is defined for.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
  "/api/v3/grids/form":
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/GridWriteModel"
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/GridFormModel"
          description: OK
          headers: {}
      tags:
      - Grids
      description: ''
      operationId: Grid_Create_Form
      summary: Grid Create Form
  "/api/v3/grids/{id}":
    get:
      summary: Get a grid
      operationId: get_grid
      tags:
      - Grids
      description: Fetches a single grid identified by its id.
      parameters:
      - name: id
        in: path
        description: Grid id
        required: true
        schema:
          type: integer
        example: 42
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/GridReadModel"
              examples:
                Simple grid:
                  "$ref": "#/components/examples/GridSimpleResponse"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the Grid does not exist or if the user does not have permission to view it.

            **Required permission** depends on the page the grid is defined for
    patch:
      summary: Update a grid
      operationId: update_grid
      tags:
      - Grids
      description: |-
        Updates the given grid by applying the attributes provided in the body. The constraints applied to the grid depend
        on the page the grid is placed in which is why the create form endpoint should be used to be guided when wanting
        to update a grid.
      parameters:
      - name: id
        in: path
        description: Grid id
        required: true
        schema:
          type: integer
        example: 42
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/GridWriteModel"
            examples:
              Simple grid patch:
                "$ref": "#/components/examples/GridSimplePatchModel"
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/GridReadModel"
              examples:
                Simple grid:
                  "$ref": "#/components/examples/GridSimpleResponse"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** The permission depends on the page the grid is placed in.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
  "/api/v3/grids/{id}/form":
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/GridWriteModel"
      parameters:
      - description: ID of the grid being modified
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                type: object
              examples:
                response:
                  value:
                    _embedded:
                      payload:
                        columnCount: 5
                        rowCount: 6
                        widgets:
                        - _type: GridWidget
                          endColumn: 3
                          endRow: 8
                          identifier: time_entries_current_user
                          startColumn: 1
                          startRow: 1
                        - _type: GridWidget
                          endColumn: 5
                          endRow: 8
                          identifier: news
                          startColumn: 4
                          startRow: 3
                        - _type: GridWidget
                          endColumn: 6
                          endRow: 3
                          identifier: documents
                          startColumn: 3
                          startRow: 1
                      schema:
                        _links: {}
                        _type: Schema
                        columnCount:
                          hasDefault: false
                          name: Number of columns
                          required: true
                          type: Integer
                          writable: true
                        createdAt:
                          hasDefault: false
                          name: Created on
                          required: true
                          type: DateTime
                          writable: false
                        id:
                          hasDefault: false
                          name: ID
                          required: true
                          type: Integer
                          writable: false
                        rowCount:
                          hasDefault: false
                          name: Number of rows
                          required: true
                          type: Integer
                          writable: true
                        scope:
                          _links: {}
                          hasDefault: false
                          name: Page
                          required: true
                          type: Href
                          writable: false
                        updatedAt:
                          hasDefault: false
                          name: Updated on
                          required: true
                          type: DateTime
                          writable: false
                        widgets:
                          _links: {}
                          hasDefault: false
                          name: Widgets
                          required: true
                          type: "[]GridWidget"
                          writable: true
                      validationErrors:
                        widgets:
                          _embedded:
                            errors:
                            - _embedded:
                                details:
                                  attribute: widgets
                              _type: Error
                              errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                              message: Widgets is outside of the grid.
                            - _embedded:
                                details:
                                  attribute: widgets
                              _type: Error
                              errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                              message: Widgets is outside of the grid.
                          _type: Error
                          errorIdentifier: urn:openproject-org:api:v3:errors:MultipleErrors
                          message: Multiple field constraints have been violated.
                    _links:
                      self:
                        href: "/api/v3/grids/2/form"
                        method: post
                      validate:
                        href: "/api/v3/grids/2/form"
                        method: post
                    _type: Form
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** depends on the page the grid is defined for.

            *Note that you will only receive this error, if you are at least allowed to see the corresponding grid.*
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the grid does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work package
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
      tags:
      - Grids
      description: ''
      operationId: Grid_Update_Form
      summary: Grid Update Form
  "/api/v3/groups":
    get:
      summary: List groups
      operationId: list_groups
      tags:
      - Groups
      description: |-
        Returns a collection of groups. The client can choose to filter the
        groups similar to how work packages are filtered. In addition to the provided
        filters, the server will reduce the result set to only contain groups, for which
        the requesting client has sufficient permissions (*view_members*, *manage_members*).
      parameters:
      - name: sortBy
        description: |-
          JSON specifying sort criteria.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported sorts are:

          + id: Sort by primary key

          + created_at: Sort by group creation datetime

          + updated_at: Sort by the time the group was updated last
        in: query
        required: false
        example: '[["id", "asc"]]'
        schema:
          default: '[["id", "asc"]]'
          type: string
      - name: select
        description: Comma separated list of properties to include.
        in: query
        required: false
        example: total,elements/name,elements/self,self
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/GroupCollectionModel"
        '403':
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** View members or manage members in any project
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
    post:
      summary: Create group
      operationId: create_group
      tags:
      - Groups
      description: Creates a new group applying the attributes provided in the body.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/GroupWriteModel"
      responses:
        '201':
          description: Created
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/GroupModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** Administrator
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _embedded:
                  details:
                    attribute: name
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: Name can't be blank.
  "/api/v3/groups/{id}":
    delete:
      summary: Delete group
      operationId: delete_group
      tags:
      - Groups
      description: Deletes the group.
      parameters:
      - name: id
        description: Group id
        example: 1
        in: path
        required: true
        schema:
          type: integer
      responses:
        '202':
          description: |-
            Returned if the group was marked for deletion.

            Note that the response body is empty as of now. In future versions of the API a body
            *might* be returned, indicating the progress of deletion.
        '403':
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** Administrator
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
        '404':
          description: |-
            Returned if the group does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** Administrator

            *Note: A client without sufficient permissions shall not be able to test for the existence of
            a version. That's why a 404 is returned here, even if a 403 might be more appropriate.*
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
    get:
      summary: Get group
      operationId: get_group
      tags:
      - Groups
      description: Fetches a group resource.
      parameters:
      - name: id
        description: Group id
        example: 1
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/GroupModel"
              examples:
                group response:
                  "$ref": "#/components/examples/GroupResponse"
        '404':
          description: |-
            Returned if the group does not exist or if the API user does not have permission to view them.

            **Required permission** If the user has the *manage members* permission in at least one project the user will be able to query all groups. If not, the user
            will be able to query all groups which are members in projects, he has the *view members* permission in.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
    patch:
      summary: Update group
      operationId: update_group
      tags:
      - Groups
      description: |-
        Updates the given group by applying the attributes provided in the body.

        Please note that the `members` array provided will override the existing set of members (similar to a PUT). A
        client thus has to provide the complete list of members the group is to have after the PATCH even if only one
        member is to be added.
      parameters:
      - name: id
        description: Group id
        example: 1
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/GroupWriteModel"
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/GroupModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** Administrator
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
        '404':
          description: |-
            Returned if the group does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission** If the user has the *manage members* permission in at least one project the user will be able to query all groups. If not, the user
            will be able to query all groups which are members in projects, he has the *view members* permission in.

            *Note: A client without sufficient permissions shall not be able to test for the existence of
            a version. That's why a 404 is returned here, even if a 403 might be more appropriate.*
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _embedded:
                  details:
                    attribute: members
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: Member is already taken.
  "/api/v3/help_texts":
    get:
      summary: List help texts
      operationId: list_help_texts
      tags:
      - Help texts
      description: List the complete collection of help texts.
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/HelpTextCollectionModel"
  "/api/v3/help_texts/{id}":
    get:
      summary: Get help text
      operationId: get_help_text
      tags:
      - Help texts
      description: Fetches the help text from the given id.
      parameters:
      - name: id
        description: Help text id
        example: 1
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/HelpTextModel"
        '404':
          description: Returned if the help text does not exist.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
  "/api/v3/meeting_rooms":
    get:
      summary: List available meeting rooms
      operationId: list_meeting_rooms
      tags:
      - Meeting Rooms
      description: |-
        Lists enabled THAPE meeting rooms as an unpaginated collection. The authenticated user must have
        the `create_meetings` permission in at least one project with meetings enabled.

        Without a time range, all enabled rooms are returned without checking occupancy. Supply both
        `startTime` and `endTime` to list rooms available for that range. Overlapping bookings exclude
        physical rooms, while online rooms remain available. Availability is checked again when creating
        a meeting; listing a room does not reserve it.

        Use a returned room's `id` as `thMeetingUpstreamRoom` when creating or updating a meeting.
      parameters:
      - name: startTime
        in: query
        required: false
        description: |-
          Start of the meeting in ISO 8601 format. Must be supplied together with `endTime`.
          Timestamp offsets are interpreted in the application's time zone.
        schema:
          type: string
          format: date-time
        example: '2030-06-02T14:00:00+08:00'
      - name: endTime
        in: query
        required: false
        description: |-
          End of the meeting in ISO 8601 format. Must be supplied together with `startTime` and be later
          than `startTime`. Timestamp offsets are interpreted in the application's time zone.
        schema:
          type: string
          format: date-time
        example: '2030-06-02T15:00:00+08:00'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MeetingRoomCollectionModel"
              example:
                _type: Collection
                total: 1
                count: 1
                _links:
                  self:
                    href: "/api/v3/meeting_rooms?endTime=2030-06-02T15%3A00%3A00%2B08%3A00&startTime=2030-06-02T14%3A00%3A00%2B08%3A00"
                _embedded:
                  elements:
                  - _type: MeetingRoom
                    id: room-1
                    name: Room 1
                    shortName: R1
                    officeAreaId: office-1
                    officeArea: Shanghai
                    location: Floor 2
        '400':
          description: |-
            Returned if only one timestamp is supplied, a timestamp is blank, or `endTime` is not later
            than `startTime`.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '401':
          description: Returned if the client is not authenticated.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '403':
          description: |-
            Returned if the authenticated user does not have the `create_meetings` permission in any
            project with meetings enabled.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '422':
          description: Returned if a timestamp is malformed (`PropertyFormatError`).
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/meetings":
    get:
      summary: List all visible meetings
      operationId: list_meetings
      tags:
      - Meetings
      description: Retrieve a paginated collection of meetings visible to the authenticated
        user.
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              examples:
                response:
                  "$ref": "#/components/examples/MeetingCollectionSimpleResponse"
              schema:
                "$ref": "#/components/schemas/MeetingCollectionModel"
    post:
      summary: Create meeting
      operationId: create_meeting
      tags:
      - Meetings
      description: |-
        Creates a new meeting applying the attributes provided in the body.

        You can use the form and schema to retrieve the valid attribute values and by that be guided towards
        successful creation.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/MeetingWriteModel"
            examples:
              create meeting:
                "$ref": "#/components/examples/MeetingCreateRequest"
      responses:
        '201':
          description: Created
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MeetingModel"
              examples:
                response:
                  "$ref": "#/components/examples/MeetingSimpleResponse"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** create meetings
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
  "/api/v3/meetings/{id}":
    get:
      summary: Get a meeting
      operationId: get_meeting
      tags:
      - Meetings
      description: Retrieve an individual meeting as identified by the id parameter
      parameters:
      - description: Meeting identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              examples:
                response:
                  "$ref": "#/components/examples/MeetingSimpleResponse"
              schema:
                "$ref": "#/components/schemas/MeetingModel"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the meeting does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view meetings in the meeting's project
    patch:
      summary: Update meeting
      operationId: update_meeting
      tags:
      - Meetings
      description: Updates the given meeting by applying the attributes provided in
        the body.
      parameters:
      - description: Meeting identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/MeetingWriteModel"
            examples:
              update meeting:
                "$ref": "#/components/examples/MeetingUpdateRequest"
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MeetingModel"
              examples:
                response:
                  "$ref": "#/components/examples/MeetingSimpleResponse"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit meetings in the meeting's project
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the meeting does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view meetings in the meeting's project
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
    delete:
      summary: Delete meeting
      operationId: delete_meeting
      tags:
      - Meetings
      description: Deletes the meeting. Participants will be notified of the cancellation.
      parameters:
      - description: Meeting identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Returned if the meeting was successfully deleted
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** delete meetings
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the meeting does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view meetings in the meeting's project
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
  "/api/v3/meetings/{id}/agenda_items":
    get:
      summary: List meeting agenda items
      operationId: list_meeting_agenda_items
      tags:
      - Meetings
      description: Lists all agenda items for the given meeting.
      parameters:
      - description: Meeting identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MeetingAgendaItemCollectionModel"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the meeting does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view meetings
  "/api/v3/meetings/{meeting_id}/agenda_items/{id}":
    get:
      summary: Get a meeting agenda item
      operationId: get_meeting_agenda_item_by_meeting
      tags:
      - Meetings
      description: Retrieve an individual agenda item of a meeting.
      parameters:
      - description: Meeting identifier
        example: 1
        in: path
        name: meeting_id
        required: true
        schema:
          type: integer
      - description: Agenda item identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MeetingAgendaItemModel"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: Returned if the agenda item or meeting does not exist or the
            client does not have sufficient permissions.
  "/api/v3/meeting_agenda_items":
    post:
      summary: Create meeting agenda item
      operationId: create_meeting_agenda_item
      tags:
      - Meetings
      description: Creates a new agenda item. The request body must link the meeting.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/MeetingAgendaItemWriteModel"
      responses:
        '201':
          description: Created
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MeetingAgendaItemModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage agendas
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: Returned if the linked meeting does not exist or the client
            does not have sufficient permissions to see it.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
  "/api/v3/meeting_agenda_items/{id}":
    get:
      summary: Get a meeting agenda item
      operationId: get_meeting_agenda_item
      tags:
      - Meetings
      description: Retrieve an individual agenda item.
      parameters:
      - description: Agenda item identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MeetingAgendaItemModel"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: Returned if the agenda item does not exist or the client does
            not have sufficient permissions.
    patch:
      summary: Update a meeting agenda item
      operationId: update_meeting_agenda_item
      tags:
      - Meetings
      description: Updates the given agenda item.
      parameters:
      - description: Agenda item identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/MeetingAgendaItemWriteModel"
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MeetingAgendaItemModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage agendas
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: Returned if the agenda item does not exist or the client does
            not have sufficient permissions.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
    delete:
      summary: Delete a meeting agenda item
      operationId: delete_meeting_agenda_item
      tags:
      - Meetings
      description: Deletes the agenda item.
      parameters:
      - description: Agenda item identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Returned if the agenda item was successfully deleted
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage agendas
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: Returned if the agenda item does not exist or the client does
            not have sufficient permissions.
  "/api/v3/meetings/{meeting_id}/agenda_items/{agenda_item_id}/outcomes":
    get:
      summary: List meeting outcomes
      operationId: list_meeting_outcomes
      tags:
      - Meetings
      description: Lists all outcomes for the given meeting agenda item.
      parameters:
      - description: Meeting identifier
        example: 1
        in: path
        name: meeting_id
        required: true
        schema:
          type: integer
      - description: Agenda item identifier
        example: 1
        in: path
        name: agenda_item_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MeetingOutcomeCollectionModel"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the agenda item or meeting does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view meetings
  "/api/v3/meetings/{meeting_id}/agenda_items/{agenda_item_id}/outcomes/{id}":
    get:
      summary: Get a meeting outcome
      operationId: get_meeting_outcome_by_agenda_item
      tags:
      - Meetings
      description: Retrieve an individual outcome of a meeting agenda item.
      parameters:
      - description: Meeting identifier
        example: 1
        in: path
        name: meeting_id
        required: true
        schema:
          type: integer
      - description: Agenda item identifier
        example: 1
        in: path
        name: agenda_item_id
        required: true
        schema:
          type: integer
      - description: Outcome identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MeetingOutcomeModel"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: Returned if the outcome, agenda item, or meeting does not exist
            or the client does not have sufficient permissions.
  "/api/v3/meeting_outcomes":
    post:
      summary: Create meeting outcome
      operationId: create_meeting_outcome
      tags:
      - Meetings
      description: Creates a new meeting outcome. The request body must link the agenda
        item.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/MeetingOutcomeWriteModel"
      responses:
        '201':
          description: Created
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MeetingOutcomeModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage outcomes
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: Returned if the linked agenda item does not exist or the client
            does not have sufficient permissions to see it.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
  "/api/v3/meeting_outcomes/{id}":
    get:
      summary: Get a meeting outcome
      operationId: get_meeting_outcome
      tags:
      - Meetings
      description: Retrieve an individual meeting outcome.
      parameters:
      - description: Outcome identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MeetingOutcomeModel"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: Returned if the outcome does not exist or the client does not
            have sufficient permissions.
    patch:
      summary: Update a meeting outcome
      operationId: update_meeting_outcome
      tags:
      - Meetings
      description: Updates the given meeting outcome.
      parameters:
      - description: Outcome identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/MeetingOutcomeWriteModel"
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MeetingOutcomeModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage outcomes
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: Returned if the outcome does not exist or the client does not
            have sufficient permissions.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
    delete:
      summary: Delete a meeting outcome
      operationId: delete_meeting_outcome
      tags:
      - Meetings
      description: Deletes the outcome.
      parameters:
      - description: Outcome identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Returned if the outcome was successfully deleted
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage outcomes
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: Returned if the outcome does not exist or the client does not
            have sufficient permissions.
  "/api/v3/meetings/{id}/attachments":
    get:
      parameters:
      - description: ID of the meeting whose attachments will be listed
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          author:
                            href: "/api/v3/users/1"
                            title: OpenProject Admin
                          container:
                            href: "/api/v3/meetings/72"
                            title: meeting
                          delete:
                            href: "/api/v3/attachments/376"
                            method: delete
                          downloadLocation:
                            href: "/api/v3/attachments/376/content"
                          self:
                            href: "/api/v3/attachments/376"
                            title: 200.gif
                        _type: Attachment
                        contentType: image/gif
                        createdAt: '2018-06-01T07:24:19.896Z'
                        description:
                          format: plain
                          html: ''
                          raw: ''
                        digest:
                          algorithm: md5
                          hash: 7ac9c97ef73d47127f590788b84c0c1c
                        fileName: some.gif
                        fileSize: 3521772
                        id: 376
                    _links:
                      self:
                        href: "/api/v3/meetings/72/attachments"
                    _type: Collection
                    count: 1
                    total: 1
              schema:
                "$ref": "#/components/schemas/Attachments_Model"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the meeting does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view meetings

            *Note: A client without sufficient permissions shall not be able to test for the existence of a meeting.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
      tags:
      - Attachments
      description: ''
      operationId: List_attachments_by_meeting
      summary: List attachments by meeting
    post:
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              "$ref": "#/components/schemas/FileUploadForm"
            encoding:
              metadata:
                contentType: application/json
              file:
                contentType: "*/*"
      parameters:
      - description: ID of the meeting to receive the attachment
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '201':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/AttachmentModel"
              examples:
                response:
                  value:
                    _embedded:
                      author:
                        _links:
                          lock:
                            href: "/api/v3/users/1/lock"
                            method: post
                            title: Set lock on admin
                          self:
                            href: "/api/v3/users/1"
                            title: OpenProject Admin
                          showUser:
                            href: "/users/1"
                            type: text/html
                          updateImmediately:
                            href: "/api/v3/users/1"
                            method: patch
                            title: Update admin
                        _type: User
                        admin: true
                        avatar: ''
                        createdAt: '2015-03-20T12:56:52.343Z'
                        email:
                        firstName: OpenProject
                        id: 1
                        identityUrl:
                        lastName: Admin
                        login: admin
                        name: OpenProject Admin
                        status: active
                        updatedAt: '2018-05-29T13:57:44.662Z'
                      container:
                        _links:
                          addAttachment:
                            href: "/api/v3/meetings/72/attachments"
                            method: post
                          attachments:
                            href: "/api/v3/meetings/72/attachments"
                          project:
                            href: "/api/v3/projects/12"
                            title: Demo project
                          self:
                            href: "/api/v3/meetings/72"
                        _type: Meeting
                        id: 72
                        title: meeting
                    _links:
                      author:
                        href: "/api/v3/users/1"
                        title: OpenProject Admin
                      container:
                        href: "/api/v3/meetings/72"
                        title: meeting
                      delete:
                        href: "/api/v3/attachments/376"
                        method: delete
                      downloadLocation:
                        href: "/api/v3/attachments/376/content"
                      self:
                        href: "/api/v3/attachments/376"
                        title: 200.gif
                    _type: Attachment
                    status: uploaded
                    contentType: image/gif
                    createdAt: '2018-06-01T07:24:19.896Z'
                    description:
                      format: plain
                      html: ''
                      raw: ''
                    digest:
                      algorithm: md5
                      hash: 7ac9c97ef73d47127f590788b84c0c1c
                    fileName: some.gif
                    fileSize: 3521772
                    id: 376
          description: Created
          headers: {}
        '400':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
                    message: The request could not be parsed as JSON.
          description: Returned if the `metadata` part contains unparsable JSON.
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to delete this attachment.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit meetings

            *Note that you will only receive this error, if you are at least allowed to see the meeting*
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the meeting does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view meetings

            *Note: A client without sufficient permissions shall not be able to test for the existence of a meeting
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: File is too large (maximum size is 5242880 Bytes).
          description: |-
            Returned if the client tries to send an invalid attachment.
            Reasons are:

            * Omitting one of the required parts (`metadata` or `file`)

            * Sending metadata or file parts in an invalid format

            * Omitting the file name (`fileName` property of metadata part)

            * Sending a file that is too large
          headers: {}
      tags:
      - Attachments
      description: Adds an attachment with the meeting as its container.
      operationId: Add_attachment_to_meeting
      summary: Add attachment to meeting
  "/api/v3/meetings/{id}/attachments/prepare":
    post:
      summary: Prepare a direct attachment upload for a meeting
      operationId: prepare_meeting_attachment_upload
      tags:
      - Attachments
      - Meetings
      description: |-
        Prepares a direct upload of an attachment for the given meeting, to be performed by the
        client without the file content passing through the OpenProject server. See
        `POST /api/v3/attachments/prepare` for a detailed description of the three-step flow this
        endpoint is the first step of.

        Unlike `POST /api/v3/attachments/prepare`, the resulting pending attachment is immediately
        associated with this meeting as its container.
      parameters:
      - name: id
        description: ID of the meeting to receive the attachment
        example: 1
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - metadata
              properties:
                metadata:
                  type: string
                  contentMediaType: application/json
                  contentSchema:
                    "$ref": "#/components/schemas/AttachmentPrepareUploadWriteModel"
                  description: |-
                    A **single** part, named `metadata`, whose value is a *JSON-encoded string*
                    conforming to the schema referenced above (see the *Model* tab for its
                    properties) - it must **not** be split into separate `fileName`, `fileSize`, ...
                    form fields. No file content is sent with this request.
                  example: '{"fileName":"cat.png","fileSize":24,"contentType":"image/png"}'
            encoding:
              metadata:
                contentType: application/json
      responses:
        '201':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/AttachmentUploadModel"
        '400':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
                message: The request could not be parsed as JSON.
          description: |-
            Returned if the client sends a not understandable request. Reasons include:

            * Omitting the `metadata` part

            * sending unparsable JSON in the metadata part
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to add attachments to this meeting.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit meetings

            *Note that you will only receive this error, if you are at least allowed to see the meeting*
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the meeting does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view meetings

            *Note: A client without sufficient permissions shall not be able to test for the existence of a meeting.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                direct uploads not available:
                  description: Returned if the OpenProject instance is not configured
                    for direct uploads.
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Direct file upload is not available due to a system configuration
                      issue. Please contact your administrator.
                missing file name:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: File can't be blank.
          description: |-
            Returned if the client tries to prepare an invalid attachment upload.
            Reasons are:

            * Omitting the file name (`fileName` property of metadata part)

            * Omitting the file size (`fileSize` property of metadata part)

            * The instance is not configured for direct uploads
  "/api/v3/meetings/{id}/form":
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/MeetingWriteModel"
      summary: Meeting update form
      operationId: meeting_update_form
      tags:
      - Meetings
      description: ''
      parameters:
      - description: Meeting identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MeetingFormModel"
          description: OK
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit meetings in the meeting's project
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
  "/api/v3/meetings/{id}/sections":
    get:
      summary: List meeting sections
      operationId: list_meeting_sections
      tags:
      - Meetings
      description: |-
        Lists all sections for the given meeting, including the backlog section as the last element.

        The backlog section is read-only and its `_links.meeting` points to the owning meeting (the
        series template for recurring meeting occurrences, otherwise the meeting itself).
      parameters:
      - description: Meeting identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MeetingSectionCollectionModel"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the meeting does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view meetings
  "/api/v3/meetings/{meeting_id}/sections/{id}":
    get:
      summary: Get a meeting section
      operationId: get_meeting_section_by_meeting
      tags:
      - Meetings
      description: |-
        Retrieve an individual section of a meeting.

        The backlog section can be retrieved via this nested endpoint even though it is not part of the
        regular `meeting.sections` association. Its `_links.self` and `_links.meeting` point to the
        canonical flat section resource and the owning meeting (the series template for recurring
        meeting occurrences).
      parameters:
      - description: Meeting identifier
        example: 1
        in: path
        name: meeting_id
        required: true
        schema:
          type: integer
      - description: Section identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MeetingSectionModel"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: Returned if the section or meeting does not exist or the client
            does not have sufficient permissions.
  "/api/v3/meeting_sections":
    post:
      summary: Create meeting section
      operationId: create_meeting_section
      tags:
      - Meetings
      description: Creates a new section. The request body must link the meeting.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/MeetingSectionWriteModel"
      responses:
        '201':
          description: Created
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MeetingSectionModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage agendas
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: Returned if the linked meeting does not exist or the client
            does not have sufficient permissions to see it.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
  "/api/v3/meeting_sections/{id}":
    get:
      summary: Get a meeting section
      operationId: get_meeting_section
      tags:
      - Meetings
      description: |-
        Retrieve an individual meeting section.

        The backlog section can be retrieved via this endpoint even though it is not part of the regular
        `meeting.sections` association. Its `_links.meeting` points to the owning meeting (the series
        template for recurring meeting occurrences).
      parameters:
      - description: Section identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MeetingSectionModel"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: Returned if the section does not exist or the client does not
            have sufficient permissions.
    patch:
      summary: Update a meeting section
      operationId: update_meeting_section
      tags:
      - Meetings
      description: |-
        Updates the given meeting section.

        The backlog section cannot be updated and will return `422 Unprocessable Entity`.
      parameters:
      - description: Section identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/MeetingSectionWriteModel"
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MeetingSectionModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage agendas
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: Returned if the section does not exist or the client does not
            have sufficient permissions.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
    delete:
      summary: Delete a meeting section
      operationId: delete_meeting_section
      tags:
      - Meetings
      description: |-
        Deletes the meeting section and all its agenda items.

        The backlog section cannot be deleted and will return `422 Unprocessable Entity`.
      parameters:
      - description: Section identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Returned if the section was successfully deleted
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage agendas
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: Returned if the section does not exist or the client does not
            have sufficient permissions.
  "/api/v3/meetings/form":
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/MeetingWriteModel"
      summary: Meeting create form
      operationId: meeting_create_form
      tags:
      - Meetings
      description: ''
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MeetingFormModel"
          description: OK
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** create meetings in any project
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
  "/api/v3/meetings/schema":
    get:
      summary: Get meeting schema
      operationId: get_meeting_schema
      tags:
      - Meetings
      description: |-
        Retrieves the schema for meetings, providing information about which properties are writable,
        their types, and constraints.
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/SchemaModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** view meetings in any project
  "/api/v3/memberships":
    get:
      summary: List memberships
      operationId: list_memberships
      tags:
      - Memberships
      description: |-
        Returns a collection of memberships. The client can choose to filter
        the memberships similar to how work packages are filtered. In addition to the
        provided filters, the server will reduce the result set to only contain memberships,
        for which the requesting client has sufficient permissions (*view_members*, *manage_members*).
      parameters:
      - name: filters
        in: query
        required: false
        schema:
          type: string
        description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/)
          endpoint. Currently supported filters are:

          + any_name_attribute: filters memberships based on the name of the principal. All possible name variants
            (and also email and login) are searched.
          + blocked: reduces the result set to all memberships that are temporarily blocked or that are not blocked
            temporarily.
          + group: filters memberships based on the name of a group. The group however is not the principal used for
            filtering. Rather, the memberships of the group are used as the filter values.
          + name: filters memberships based on the name of the principal. Note that only the name is used which depends
            on a setting in the OpenProject instance.
          + principal: filters memberships based on the id of the principal.
          + project: filters memberships based on the id of the project.
          + role: filters memberships based on the id of any role assigned to the membership.
          + status: filters memberships based on the status of the principal.
          + created_at: filters memberships based on the time the membership was created.
          + updated_at: filters memberships based on the time the membership was updated last.
        examples:
          name-filter:
            summary: Filtering on the name of the principal
            value: '[{ "name": { "operator": "=", "values": ["A User"] } }]'
          global-memberships:
            summary: Get memberships for global roles
            value: '[{ "project": { "operator": "!*", "values": null } }]'
      - name: sortBy
        in: query
        required: false
        schema:
          default: '[["id", "asc"]]'
          type: string
        description: |-
          JSON specifying sort criteria.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/)
          endpoint. Currently supported sorts are:

          + id: Sort by primary key
          + name: Sort by the name of the principal. Note that this depends on the setting for how the name is to be
            displayed at least for users.
          + email: Sort by the email address of the principal. Groups and principal users, which do not have an email,
            are sorted last.
          + status: Sort by the status of the principal. Groups and principal users, which do not have a status, are
            sorted together with the active users.
          + created_at: Sort by membership creation datetime
          + updated_at: Sort by the time the membership was updated last
        example: '[["id", "asc"]]'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MembershipCollectionModel"
              examples:
                simple membership collection:
                  "$ref": "#/components/examples/MembershipSimpleCollectionResponse"
        '400':
          "$ref": "#/components/responses/InvalidQuery"
        '403':
          description: Returned if the client is not logged in and login is required.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to view this resource.
    post:
      summary: Create a membership
      operationId: create_membership
      tags:
      - Memberships
      description: |-
        Creates a new membership applying the attributes provided in the body.

        You can use the form and schema to retrieve the valid attribute values and by that be guided towards successful
        creation.

        By providing a `notificationMessage` within the `_meta` block of the payload, the client can include a customized
        message to the user of the newly created membership. In case of a group, the message will be sent to every user
        belonging to the group.

        By including `{ "sendNotifications": false }` within the `_meta` block of the payload, no notifications is send
        out at all.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/MembershipWriteModel"
            examples:
              global role:
                "$ref": "#/components/examples/MembershipCreateRequestGlobalRole"
              no notification:
                "$ref": "#/components/examples/MembershipCreateRequestNoNotification"
              custom message:
                "$ref": "#/components/examples/MembershipCreateRequestCustomMessage"
      responses:
        '201':
          description: Created
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MembershipReadModel"
              examples:
                simple membership:
                  "$ref": "#/components/examples/MembershipSimpleResponse"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** Manage members
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _embedded:
                  details:
                    attribute: project
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: Project can't be blank.
          description: |-
            Returned if:

            - a constraint for a property was violated (`PropertyConstraintViolation`)
  "/api/v3/memberships/available_projects":
    get:
      summary: Available projects for memberships
      operationId: get_memberships_available_projects
      tags:
      - Memberships
      description: |-
        Gets a list of projects in which a membership can be created in. The list contains all projects in which the user
        issuing the request has the manage members permissions.
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ProjectCollectionModel"
              examples:
                simple project collection:
                  "$ref": "#/components/examples/ProjectCollection"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage members
  "/api/v3/memberships/form":
    post:
      summary: Form create membership
      operationId: form_create_membership
      tags:
      - Memberships
      description: |-
        Requests and validates the creation form for memberships. The request payload, if sent, is validated. The form
        endpoint itself does not create a membership.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/MembershipWriteModel"
            examples:
              global role:
                "$ref": "#/components/examples/MembershipCreateRequestGlobalRole"
              no notification:
                "$ref": "#/components/examples/MembershipCreateRequestNoNotification"
              custom message:
                "$ref": "#/components/examples/MembershipCreateRequestCustomMessage"
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MembershipFormModel"
              examples:
                form:
                  "$ref": "#/components/examples/MembershipFormResponse"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage memberships in any project
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
  "/api/v3/memberships/schema":
    get:
      summary: Schema membership
      operationId: get_membership_schema
      tags:
      - Memberships
      description: Retrieves the schema for the membership resource object.
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MembershipSchemaModel"
              examples:
                schema:
                  "$ref": "#/components/examples/MembershipSchemaResponse"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions to see the schema.

            **Required permission:** manage members or view memberships on any project
  "/api/v3/memberships/{id}":
    delete:
      summary: Delete membership
      operationId: delete_membership
      tags:
      - Memberships
      description: Deletes the membership.
      parameters:
      - name: id
        description: Membership id
        in: path
        required: true
        example: 1
        schema:
          type: integer
      responses:
        '204':
          description: Returned if the membership was successfully deleted
        '403':
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage members
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the membership does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view members

            *Note: A client without sufficient permissions shall not be able to test for the existence of
            a version. That's why a 404 is returned here, even if a 403 might be more appropriate.*
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
    get:
      summary: Get a membership
      operationId: get_membership
      description: Retrieves a membership resource identified by the given id.
      tags:
      - Memberships
      parameters:
      - name: id
        description: Membership id
        in: path
        required: true
        example: 1
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MembershipReadModel"
              examples:
                simple membership:
                  "$ref": "#/components/examples/MembershipSimpleResponse"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the membership does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view members **or** manage members

            *Note: A client without sufficient permissions shall not be able to test for the existence of
            a membership. That's why a 404 is returned here, even if a 403 might be more appropriate.*
    patch:
      summary: Update membership
      operationId: update_membership
      description: |-
        Updates the given membership by applying the attributes provided in the body.

        By providing a `notificationMessage` within the `_meta` block of the payload, the client can include a customized message to the user
        of the updated membership. In case of a group, the message will be sent to every user belonging to the group.

        By including `{ "sendNotifications": false }` within the `_meta` block of the payload, no notifications is send out at all.
      tags:
      - Memberships
      parameters:
      - name: id
        description: Membership id
        in: path
        required: true
        example: 1
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/MembershipWriteModel"
            examples:
              add roles:
                "$ref": "#/components/examples/MembershipUpdateAdditionalRoles"
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MembershipReadModel"
              examples:
                simple membership:
                  "$ref": "#/components/examples/MembershipSimpleResponse"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** Manage members in the membership's project.
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the membership does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view member

            *Note: A client without sufficient permissions shall not be able to test for the existence of
            a version. That's why a 404 is returned here, even if a 403 might be more appropriate.*
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _embedded:
                  details:
                    attribute: roles
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: Roles has an unassignable role.
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
  "/api/v3/memberships/{id}/form":
    post:
      summary: Form update membership
      operationId: form_update_membership
      tags:
      - Memberships
      description: |-
        Requests and validates the update form for a membership identified by the given id. The request payload, if sent,
        is validated. The form endpoint itself does not change the membership.
      parameters:
      - name: id
        description: Membership id
        in: path
        required: true
        example: 1
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/MembershipWriteModel"
            examples:
              no notification:
                "$ref": "#/components/examples/MembershipCreateRequestNoNotification"
              custom message:
                "$ref": "#/components/examples/MembershipCreateRequestCustomMessage"
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MembershipReadModel"
              examples:
                simple membership:
                  "$ref": "#/components/examples/MembershipSimpleResponse"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage versions in the version's project
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
  "/api/v3/my_preferences":
    get:
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _links:
                      self:
                        href: "/api/v3/my_preferences"
                      user:
                        href: "/api/v3/users/1"
                        title: John Sheppard
                      updateImmediately:
                        href: "/api/v3/users/3/preferences"
                        method: patch
                    _type: UserPreferences
                    commentSortDescending: true
                    disableKeyboardShortcuts: false
                    timeZone: Europe/Berlin
                    warnOnLeavingUnsaved: true
                    notifications:
                      watched: false
                      involved: true
                      mentioned: false
                      shared: true
                      newsAdded: false,
                      newsCommented: false
                      documentAdded: false
                      forumMessages: false
                      wikiPageAdded: false
                      wikiPageUpdated: false
                      membershipAdded: false
                      membershipUpdated: false
                      workPackageCommented: false
                      workPackageProcessed: false
                      workPackagePrioritized: false
                      workPackageScheduled: false
                      _links:
                        project:
                          href:
              schema:
                "$ref": "#/components/schemas/UserPreferencesModel"
          description: OK
          headers: {}
        '401':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                    message: You need to be authenticated to access this resource.
          description: Returned if no user is currently authenticated
          headers: {}
      tags:
      - UserPreferences
      description: ''
      operationId: Show_my_preferences
      summary: Show my preferences
    patch:
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _links:
                      self:
                        href: "/api/v3/my_preferences"
                      user:
                        href: "/api/v3/users/1"
                        title: John Sheppard
                      updateImmediately:
                        href: "/api/v3/users/3/preferences"
                        method: patch
                    _type: UserPreferences
                    commentSortDescending: true
                    disableKeyboardShortcuts: false
                    timeZone: Europe/Berlin
                    warnOnLeavingUnsaved: true
                    notifications:
                      watched: false
                      involved: true
                      mentioned: false
                      shared: true
                      newsAdded: false,
                      newsCommented: false
                      documentAdded: false
                      forumMessages: false
                      wikiPageAdded: false
                      wikiPageUpdated: false
                      membershipAdded: false
                      membershipUpdated: false
                      workPackageCommented: false
                      workPackageProcessed: false
                      workPackagePrioritized: false
                      workPackageScheduled: false
                      _links:
                        project:
                          href:
              schema:
                "$ref": "#/components/schemas/UserPreferencesModel"
          description: OK
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '401':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                    message: You need to be authenticated to access this resource.
          description: Returned if no user is currently authenticated
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Time zone is not set to one of the allowed values.
          description: |-
            Returned if the update contains invalid properties.
            Reasons are:

            * Specifying an invalid type

            * Using an unknown time zone
          headers: {}
      tags:
      - UserPreferences
      description: When calling this endpoint the client provides a single object,
        containing the properties that it wants to change, in the body.
      operationId: Update_UserPreferences
      requestBody:
        content:
          application/json:
            schema:
              example:
                autoHidePopups: true
                timeZone: Europe/Paris
              properties:
                autoHidePopups:
                  type: boolean
                timeZone:
                  type: string
              type: object
      summary: Update my preferences
  "/api/v3/news":
    get:
      parameters:
      - description: Page number inside the requested collection.
        example: 25
        in: query
        name: offset
        required: false
        schema:
          default: 1
          type: integer
      - description: Number of elements to display per page.
        example: 25
        in: query
        name: pageSize
        required: false
        schema:
          type: integer
      - description: |-
          JSON specifying sort criteria.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported sorts are:

          + id: Sort by primary key

          + created_at: Sort by news creation datetime
        example: '[["created_at", "asc"]]'
        in: query
        name: sortBy
        required: false
        schema:
          type: string
      - description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported filters are:

          + project_id: Filter news by project
        example: '[{ "project_id": { "operator": "=", "values": ["1", "2"] } }]'
        in: query
        name: filters
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          author:
                            href: "/api/v3/users/2"
                            title: Peggie Feeney
                          project:
                            href: "/api/v3/projects/1"
                            title: Seeded Project
                          self:
                            href: "/api/v3/news/1"
                            title: asperiores possimus nam doloribus ab
                        _type: News
                        createdAt: '2015-03-20T12:57:01.209Z'
                        description:
                          format: markdown
                          html: "<p>Videlicet deserunt aequitas cognatus. Concedo
                            quia est quia pariatur vorago vallum. Calco autem atavus
                            accusamus conscendo cornu ulterius. Tam patria ago consectetur
                            ventito sustineo nihil caecus. Supra officiis eos velociter
                            somniculosus tonsor qui. Suffragium aduro arguo angustus
                            cogito quia tolero vulnus. Supplanto sortitus cresco apud
                            vestrum qui.</p>"
                          raw: Videlicet deserunt aequitas cognatus. Concedo quia
                            est quia pariatur vorago vallum. Calco autem atavus accusamus
                            conscendo cornu ulterius. Tam patria ago consectetur ventito
                            sustineo nihil caecus. Supra officiis eos velociter somniculosus
                            tonsor qui. Suffragium aduro arguo angustus cogito quia
                            tolero vulnus. Supplanto sortitus cresco apud vestrum
                            qui.
                        id: 1
                        summary: Celebrer spiculum colo viscus claustrum atque. Id
                          nulla culpa sumptus. Comparo crapula depopulo demonstro.
                        title: asperiores possimus nam doloribus ab
                      - _links:
                          author:
                            href: "/api/v3/users/2"
                            title: Peggie Feeney
                          project:
                            href: "/api/v3/projects/1"
                            title: Seeded Project
                          self:
                            href: "/api/v3/news/2"
                            title: terminatio tutamen. Officia adeptio sp
                        _type: News
                        createdAt: '2015-03-20T12:57:01.262Z'
                        description:
                          format: markdown
                          html: "<p>Amicitia alius cattus voluntarius. Virgo viduo
                            terminatio tutamen. Officia adeptio spectaculum atavus
                            nisi cum concido bis. Harum caecus auxilium sol theatrum
                            eaque consequatur. Omnis aeger suus adipisci cicuta. Cur
                            delicate alias curto cursim atqui talio fugiat.</p>"
                          raw: Amicitia alius cattus voluntarius. Virgo viduo terminatio
                            tutamen. Officia adeptio spectaculum atavus nisi cum concido
                            bis. Harum caecus auxilium sol theatrum eaque consequatur.
                            Omnis aeger suus adipisci cicuta. Cur delicate alias curto
                            cursim atqui talio fugiat.
                        id: 2
                        summary: Consequatur sequi surculus creo tui aequitas.
                        title: terminatio tutamen. Officia adeptio sp
                    _links:
                      changeSize:
                        href: "/api/v3/news?offset=1&pageSize=%7Bsize%7D"
                        templated: true
                      jumpTo:
                        href: "/api/v3/news?offset=%7Boffset%7D&pageSize=2"
                        templated: true
                      nextByOffset:
                        href: "/api/v3/news?offset=2&pageSize=2"
                      self:
                        href: "/api/v3/news?offset=1&pageSize=2"
                    _type: Collection
                    count: 2
                    offset: 1
                    pageSize: 2
                    total: 78
              schema:
                "$ref": "#/components/schemas/List_of_NewsModel"
          description: OK
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to view this resource.
          description: Returned if the client is not logged in and login is required.
          headers: {}
      tags:
      - News
      description: Lists news. The news returned depend on the provided parameters
        and also on the requesting user's permissions.
      operationId: List_News
      summary: List News
    post:
      summary: Create News
      operationId: create_news
      tags:
      - News
      description: |-
        Creates a news entry. Only administrators and users with "Manage news" permission in the given project are eligible.
        When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/NewsCreateModel"
      responses:
        '201':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/NewsModel"
          description: Created
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to create new news.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** Administrator, Manage news permission in the project
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _embedded:
                  details:
                    attribute: title
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: Title can't be blank.
          description: |-
            Returned if:

            * the client tries to modify a read-only property (`PropertyIsReadOnly`)

            * a constraint for a property was violated (`PropertyConstraintViolation`)
  "/api/v3/news/{id}":
    get:
      parameters:
      - description: news id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      author:
                        _type: User...
                      project:
                        _type: Project...
                    _links:
                      author:
                        href: "/api/v3/users/2"
                        title: Peggie Feeney
                      project:
                        href: "/api/v3/projects/1"
                        title: A project
                      self:
                        href: "/api/v3/news/1"
                        title: asperiores possimus nam doloribus ab
                    _type: News
                    createdAt: '2015-03-20T12:57:01.601Z'
                    description:
                      format: markdown
                      html: "<p>Videlicet deserunt aequitas cognatus. Concedo quia
                        est quia pariatur vorago vallum. Calco autem atavus accusamus
                        conscendo cornu ulterius. Tam patria ago consectetur ventito
                        sustineo nihil caecus. Supra officiis eos velociter somniculosus
                        tonsor qui. Suffragium aduro arguo angustus cogito quia tolero
                        vulnus. Supplanto sortitus cresco apud vestrum qui.</p>"
                      raw: Videlicet deserunt aequitas cognatus. Concedo quia est
                        quia pariatur vorago vallum. Calco autem atavus accusamus
                        conscendo cornu ulterius. Tam patria ago consectetur ventito
                        sustineo nihil caecus. Supra officiis eos velociter somniculosus
                        tonsor qui. Suffragium aduro arguo angustus cogito quia tolero
                        vulnus. Supplanto sortitus cresco apud vestrum qui.
                    id: 1
                    summary: Celebrer spiculum colo viscus claustrum atque. Id nulla
                      culpa sumptus. Comparo crapula depopulo demonstro.
                    title: asperiores possimus nam doloribus ab
              schema:
                "$ref": "#/components/schemas/NewsModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the news does not exist or if the user does not have permission to view it.

            **Required permission** being member of the project the news belongs to
          headers: {}
      tags:
      - News
      description: ''
      operationId: View_news
      summary: View news
    patch:
      summary: Update news
      operationId: update_news
      tags:
      - News
      description: |-
        Updates the news's writable attributes.
        When calling this endpoint the client provides a single object, containing the properties and links to be updated, in the body.
      parameters:
      - description: News id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/NewsCreateModel"
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/NewsModel"
          description: OK
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to update this news.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** Administrators, Manage news permission
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified news does not exist or you do not have permission
                  to view it.
          description: |-
            Returned if the news entry does not exist or if the API user does not have the necessary permissions to update it.

            **Required permission:** Administrators, Manage news permission
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _embedded:
                  details:
                    attribute: title
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: Title can't be blank.
          description: |-
            Returned if:

            * the client tries to modify a read-only property (`PropertyIsReadOnly`)

            * a constraint for a property was violated (`PropertyConstraintViolation`)
    delete:
      summary: Delete news
      operationId: delete_news
      description: Permanently deletes the specified news entry.
      tags:
      - News
      parameters:
      - description: News id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '202':
          description: |-
            Returned if the news was deleted successfully.

            Note that the response body is empty as of now. In future versions of the API a body
            *might* be returned, indicating the progress of deletion.
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to delete this news entry
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** Administrators and Manage news permission
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified news does not exist.
          description: Returned if the news does not exist.
  "/api/v3/notifications":
    get:
      summary: Get notification collection
      operationId: list_notifications
      tags:
      - Notifications
      description: |-
        Returns the collection of available in-app notifications. The notifications returned depend on the provided
        parameters and also on the requesting user's permissions.

        Contrary to most collections, this one also links to and embeds schemas for the `details` properties of the notifications returned.
        This is an optimization. Clients will receive the information necessary to display the various types of details that a notification
        can carry.
      parameters:
      - name: offset
        description: Page number inside the requested collection.
        in: query
        example: 25
        required: false
        schema:
          default: 1
          type: integer
      - name: pageSize
        description: Number of elements to display per page.
        in: query
        example: 25
        required: false
        schema:
          default: 20
          type: integer
      - name: sortBy
        in: query
        description: |-
          JSON specifying sort criteria.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported sorts are:

          + id: Sort by primary key

          + reason: Sort by notification reason

          + readIAN: Sort by read status
        example: '[["reason", "asc"]]'
        required: false
        schema:
          type: string
      - name: groupBy
        in: query
        description: |-
          string specifying group_by criteria.

          + reason: Group by notification reason

          + project: Sort by associated project
        example: reason
        required: false
        schema:
          type: string
      - name: filters
        in: query
        description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported filters are:

          + id: Filter by primary key

          + project: Filter by the project the notification was created in

          + readIAN: Filter by read status

          + reason: Filter by the reason, e.g. 'mentioned' or 'assigned' the notification was created because of

          + resourceId: Filter by the id of the resource the notification was created for. Ideally used together with the `resourceType` filter.

          + resourceType: Filter by the type of the resource the notification was created for. Ideally used together with the `resourceId` filter.
        example: '[{ "readIAN": { "operator": "=", "values": ["t"] } }]'
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/NotificationCollectionModel"
              examples:
                Collection of notifications:
                  "$ref": "#/components/examples/NotificationCollection"
          description: OK
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to view this resource.
          description: Returned if the client is not logged in and login is required.
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
                message: Filters Invalid filter does not exist.
          description: Returned if the client sends invalid request parameters e.g.
            filters
  "/api/v3/notifications/read_ian":
    post:
      summary: Read all notifications
      operationId: read_notifications
      tags:
      - Notifications
      description: |-
        Marks the whole notification collection as read. The collection contains only elements the authenticated user can
        see, and can be further reduced with filters.
      parameters:
      - name: filters
        in: query
        description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/)
          endpoint. Currently supported filters are:

          + id: Filter by primary key

          + project: Filter by the project the notification was created in

          + reason: Filter by the reason, e.g. 'mentioned' or 'assigned' the notification was created because of

          + resourceId: Filter by the id of the resource the notification was created for. Ideally used together with the
            `resourceType` filter.

          + resourceType: Filter by the type of the resource the notification was created for. Ideally used together with
            the `resourceId` filter.
        example: '[{ "reason": { "operator": "=", "values": ["mentioned"] } }]'
        required: false
        schema:
          type: string
      responses:
        '204':
          description: OK
        '400':
          description: Returned if the request is not properly formatted.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
                message:
                - Filters Invalid filter does not exist.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
  "/api/v3/notifications/unread_ian":
    post:
      summary: Unread all notifications
      operationId: unread_notifications
      tags:
      - Notifications
      description: |-
        Marks the whole notification collection as unread. The collection contains only elements the authenticated user can
        see, and can be further reduced with filters.
      parameters:
      - name: filters
        in: query
        description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/)
          endpoint. Currently supported filters are:

          + id: Filter by primary key

          + project: Filter by the project the notification was created in

          + reason: Filter by the reason, e.g. 'mentioned' or 'assigned' the notification was created because of

          + resourceId: Filter by the id of the resource the notification was created for. Ideally used together with the
            `resourceType` filter.

          + resourceType: Filter by the type of the resource the notification was created for. Ideally used together with
            the `resourceId` filter.
        example: '[{ "reason": { "operator": "=", "values": ["mentioned"] } }]'
        required: false
        schema:
          type: string
      responses:
        '204':
          description: OK
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
  "/api/v3/notifications/{id}":
    get:
      summary: Get the notification
      operationId: view_notification
      tags:
      - Notifications
      description: Returns the notification identified by the notification id.
      parameters:
      - name: id
        in: path
        description: notification id
        example: 1
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/NotificationModel"
              examples:
                Date alert notification:
                  "$ref": "#/components/examples/DateAlertNotification"
                Mentioned notification:
                  "$ref": "#/components/examples/MentionedNotification"
          description: OK
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the notification does not exist or if the user does not have permission to view it.

            **Required permission** being recipient of the notification
  "/api/v3/notifications/{notification_id}/details/{id}":
    get:
      summary: Get a notification detail
      operationId: view_notification_detail
      tags:
      - Notifications
      - Values::Property
      description: Returns an individual detail of a notification identified by the
        notification id and the id of the detail.
      parameters:
      - name: notification_id
        in: path
        description: notification id
        example: 1
        required: true
        schema:
          type: integer
      - name: id
        in: path
        description: detail id
        example: 0
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ValuesPropertyModel"
              examples:
                Start date notification detail:
                  "$ref": "#/components/examples/ValuesPropertyStartDate"
                Due date notification detail:
                  "$ref": "#/components/examples/ValuesPropertyDueDate"
                Date notification detail for milestone work package:
                  "$ref": "#/components/examples/ValuesPropertyDate"
          description: OK
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the notification or the detail of it does not exist or if the user does not have permission to view it.

            **Required permission** being recipient of the notification
  "/api/v3/notifications/{id}/read_ian":
    post:
      summary: Read notification
      operationId: read_notification
      tags:
      - Notifications
      description: Marks the given notification as read.
      parameters:
      - name: id
        in: path
        description: notification id
        example: 1
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: OK
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the notification does not exist or if the user does not have permission to view it.

            **Required permission** being recipient of the notification
  "/api/v3/notifications/{id}/unread_ian":
    post:
      summary: Unread notification
      operationId: unread_notification
      tags:
      - Notifications
      description: Marks the given notification as unread.
      parameters:
      - name: id
        in: path
        description: notification id
        example: 1
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: OK
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the notification does not exist or if the user does not have permission to view it.

            **Required permission** being recipient of the notification
  "/api/v3/oauth_applications/{id}":
    get:
      summary: Get the oauth application.
      operationId: get_oauth_application
      tags:
      - OAuth 2
      description: |-
        Retrieves the OAuth 2 provider application for the given identifier. The secret will not be part of the response,
        instead a `confidential` flag is indicating, whether there is a secret or not.
      parameters:
      - name: id
        description: OAuth application id
        in: path
        required: true
        schema:
          type: integer
        example: 1337
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/OAuthApplicationReadModel"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** admin
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: Returned if the application does not exist.
  "/api/v3/oauth_client_credentials/{id}":
    get:
      summary: Get the oauth client credentials object.
      operationId: get_oauth_client_credentials
      tags:
      - OAuth 2
      description: |-
        Retrieves the OAuth 2 client credentials for the given identifier. The secret will not be part of the response,
        instead a `confidential` flag is indicating, whether there is a secret or not.
      parameters:
      - name: id
        description: OAuth Client Credentials id
        in: path
        required: true
        schema:
          type: integer
        example: 1337
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/OAuthClientCredentialsReadModel"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** admin
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: Returned if the object does not exist.
  "/api/v3/placeholder_users":
    get:
      summary: List placehoder users
      operationId: list_placeholder_users
      tags:
      - Principals
      description: |-
        List all placeholder users. This can only be accessed if the requesting user has the global permission
        `manage_placeholder_user` or `manage_members` in any project.
      parameters:
      - name: filters
        description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint.
          Currently supported filters are:

          - name: filters placeholder users by the name.
          - group: filters placeholder by the group it is contained in.
          - status: filters placeholder by the status it has.
        in: query
        required: false
        schema:
          type: string
        example: '[{ "name": { "operator": "~", "values": ["Darth"] } }]'
      - name: select
        description: Comma separated list of properties to include.
        in: query
        required: false
        schema:
          type: string
        example: total,elements/name,elements/self,self
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/PrincipalCollectionModel"
        '400':
          description: Returned if the client sends invalid request parameters e.g.
            filters
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
                message: Filters Invalid filter does not exist.
    post:
      summary: Create placeholder user
      operationId: create_placeholder_user
      tags:
      - Principals
      description: |-
        Creates a new placeholder user. Only administrators and users with `manage_placeholder_user` global permission are
        allowed to do so. When calling this endpoint the client provides a single object, containing at least the
        properties and links that are required, in the body.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PlaceholderUserCreateModel"
      responses:
        '201':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/PlaceholderUserModel"
          description: Created
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to create new placeholder users.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** Administrator
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _embedded:
                  details:
                    attribute: name
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: Name has already been taken.
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
  "/api/v3/placeholder_users/{id}":
    delete:
      summary: Delete placeholder user
      operationId: delete_placeholder_user
      description: Set the specified placeholder user to deleted status.
      tags:
      - Principals
      parameters:
      - description: Placeholder user id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '202':
          description: |-
            Returned if the group was marked for deletion.

            Note that the response body is empty as of now. In future versions of the API a body
            *might* be returned, indicating the progress of deletion.
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to delete the account of this user.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** `manage_placeholder_users`
        '404':
          description: Returned if the placeholder user does not exist.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified placeholder user does not exist.
    get:
      summary: View placeholder user
      operationId: view_placeholder_user
      description: Return the placeholder user resource.
      tags:
      - Principals
      parameters:
      - description: The placeholder user id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/PlaceholderUserModel"
              examples:
                placeholder user response:
                  "$ref": "#/components/examples/PlaceholderUserResponse"
          description: OK
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified placeholder user does not exist or you do not
                  have permission to view them.
          description: |-
            Returned if the user does not exist or if the API user does not have permission to view them.

            **Required permission**: `manage_placeholder_users`
    patch:
      summary: Update placeholder user
      operationId: update_placeholder_user
      tags:
      - Principals
      description: |-
        Updates the placeholder user's writable attributes.
        When calling this endpoint the client provides a single object, containing at least the properties and links
        that are required, in the body.
      parameters:
      - description: Placeholder user id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PlaceholderUserCreateModel"
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/PlaceholderUserModel"
          description: OK
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to update the account of this user.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission**: `manage_placeholder_users`
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified placeholder user does not exist.
          description: Returned if the placeholder user does not exist.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _embedded:
                  details:
                    attribute: name
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: Name has already been taken.
          description: |-
            Returned if:

            - the client tries to modify a read-only property (`PropertyIsReadOnly`)
            - a constraint for a property was violated (`PropertyConstraintViolation`)
  "/api/v3/portfolios":
    get:
      summary: List portfolios
      operationId: list_portfolios
      tags:
      - Portfolios
      description: Returns a collection of portfolios. The collection can be filtered
        via query parameters similar to how work packages are filtered. In addition
        to the provided filter, the result set is always limited to only contain portfolios
        the client is allowed to see.
      parameters:
      - name: filters
        schema:
          type: string
        in: query
        required: false
        description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openportfolio.org/docs/api/endpoints/queries/) endpoint.
          Currently supported filters are:

          + active: based on the active property of the portfolio
          + ancestor: filters portfolios by their ancestor. A portfolio is not considered to be its own ancestor.
          + available_project_attributes: filters portfolios based on the activated project attributes.
          + created_at: based on the time the portfolio was created
          + favorited: based on the favorited property of the portfolio
          + id: based on portfolios' id.
          + latest_activity_at: based on the time the last activity was registered on a portfolio.
          + name_and_identifier: based on both the name and the identifier.
          + parent_id: filters portfolios by their parent.
          + principal: based on members of the portfolio.
          + project_phase_any: based on the project phases active in a portfolio.
          + project_status_code: based on status code of the portfolio
          + storage_id: filters portfolios by linked storages
          + storage_url: filters portfolios by linked storages identified by the host url
          + type_id: based on the types active in a portfolio.
          + user_action: based on the actions the current user has in the portfolio.
          + visible: based on the visibility for the user (id) provided as the filter value. This filter is useful for admins to identify the portfolios visible to a user.

          There might also be additional filters based on the custom fields that have been configured.

          Each defined lifecycle step will also define a filter in this list endpoint. Given that the elements are not
          static but rather dynamically created on each OpenProject instance, a list cannot be provided. Those filters follow the schema:
          + project_start_gate_[id]: a filter on a project phase's start gate active in a portfolio. The id is the id of the phase the gate belongs to.
          + project_finish_gate_[id]: a filter on a project phase's finish gate active in a portfolio. The id is the id of the phase the gate belongs to.
          + project_phase_[id]: a filter on a project phase active in a portfolio. The id is the id of the phase queried for.
        example: '[{ "ancestor": { "operator": "=", "values": ["1"] } }]'
      - name: sortBy
        schema:
          type: string
        in: query
        required: false
        description: |-
          JSON specifying sort criteria.
          Currently supported orders are:

          + id
          + name
          + typeahead (sorting by hierarchy and name)
          + created_at
          + public
          + latest_activity_at
          + required_disk_space

          There might also be additional orders based on the custom fields that have been configured.
        example: '[["id", "asc"]]'
      - name: select
        schema:
          type: string
        in: query
        required: false
        description: Comma separated list of properties to include.
        example: total,elements/identifier,elements/name
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/PortfolioCollectionModel"
              examples:
                simple portfolio collection:
                  "$ref": "#/components/examples/PortfolioCollection"
        '400':
          description: Returned if the client sends invalid request parameters e.g.
            filters
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
                message: Filters Invalid filter does not exist.
  "/api/v3/portfolios/{id}":
    get:
      parameters:
      - description: Portfolio id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/PortfolioModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the portfolio does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** any permission in the portfolio

            *Note: A client without sufficient permissions shall not be able to test for the existence of a portfolio.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
      tags:
      - Portfolios
      description: ''
      operationId: View_portfolio
      summary: View portfolio
    patch:
      parameters:
      - description: Portfolio id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProjectWriteModel"
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/PortfolioModel"
              examples:
                with custom fields:
                  "$ref": "#/components/examples/Portfolio"
          description: OK
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit project for the portfolio to be altered
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the portfolio does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view project

            *Note: A client without sufficient permissions shall not be able to test for the existence of
            a version. That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _embedded:
                      details:
                        attribute: name
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Name can't be blank.
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
          headers: {}
      tags:
      - Portfolios
      description: Updates the given portfolio by applying the attributes provided
        in the body.
      operationId: Update_Portfolio
      summary: Update Portfolio
    delete:
      parameters:
      - description: Portfolio id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: |-
            Returned if the portfolio was successfully deleted. There is currently no endpoint to query for the actual deletion status.
            Such an endpoint _might_ be added in the future.
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** admin
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the portfolio does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** any permission in the portfolio

            *Note: A client without sufficient permissions shall not be able to test for the existence of
            a version. That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _embedded:
                      details:
                        attribute: base
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Work packages in non descendant projects reference versions
                      of the portfolio or its descendants.
          description: |-
            Returned if the portfolio cannot be deleted. This can happen when there are still references to the portfolio in other workspaces
            that need to be severed at first.
          headers: {}
      tags:
      - Portfolios
      description: |-
        Deletes the portfolio permanently. As this is a lengthy process, the actual deletion is carried out asynchronously.
        So the portfolio might exist well after the request has returned successfully. To prevent unwanted changes to
        the portfolio scheduled for deletion, it is archived at once.
      operationId: Delete_Portfolio
      summary: Delete Portfolio
  "/api/v3/portfolios/{id}/form":
    post:
      parameters:
      - description: Portfolio id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
            examples:
              with custom fields:
                "$ref": "#/components/examples/PortfolioBody"
              empty:
                description: Empty request to get the form initially in order to start
                  the guided update of a portfolio
                value: {}
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ProjectFormModel"
          description: OK
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit workspace in the portfolio
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
      tags:
      - Portfolios
      description: ''
      operationId: Portfolio_update_form
      summary: Portfolio update form
  "/api/v3/posts/{id}":
    get:
      parameters:
      - description: Post's identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      project:
                        _type: Project...
                    _links:
                      addAttachment:
                        href: "/api/v3/posts/1/attachments"
                        method: post
                      attachments:
                        href: "/api/v3/posts/1/attachments"
                      project:
                        href: "/api/v3/projects/1"
                        title: A project with a title
                      self:
                        href: "/api/v3/posts/1"
                    _type: Post
                    id: 1
                    subject: A post with a subject
              schema:
                "$ref": "#/components/schemas/PostModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the post does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view messages in the post's project
          headers: {}
      tags:
      - Posts
      description: Retrieve an individual post as identified by the id parameter
      operationId: View_Post
      summary: View Post
  "/api/v3/posts/{id}/attachments":
    get:
      parameters:
      - description: ID of the post whose attachments will be listed
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          author:
                            href: "/api/v3/users/1"
                            title: OpenProject Admin
                          container:
                            href: "/api/v3/posts/72"
                            title: wiki
                          delete:
                            href: "/api/v3/attachments/376"
                            method: delete
                          downloadLocation:
                            href: "/api/v3/attachments/376/content"
                          self:
                            href: "/api/v3/attachments/376"
                            title: 200.gif
                        _type: Attachment
                        contentType: image/gif
                        createdAt: '2018-06-01T07:24:19.706Z'
                        description:
                          format: plain
                          html: ''
                          raw: ''
                        digest:
                          algorithm: md5
                          hash: 7ac9c97ef73d47127f590788b84c0c1c
                        fileName: some.gif
                        fileSize: 3521772
                        id: 376
                    _links:
                      self:
                        href: "/api/v3/posts/72/attachments"
                    _type: Collection
                    count: 1
                    total: 1
              schema:
                "$ref": "#/components/schemas/Attachments_Model"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the post does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view messages

            *Note: A client without sufficient permissions shall not be able to test for the existence of a post.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
      tags:
      - Attachments
      description: ''
      operationId: List_attachments_by_post
      summary: List attachments by post
    post:
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              "$ref": "#/components/schemas/FileUploadForm"
            encoding:
              metadata:
                contentType: application/json
              file:
                contentType: "*/*"
      parameters:
      - description: ID of the post to receive the attachment
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '201':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/AttachmentModel"
              examples:
                response:
                  value:
                    _embedded:
                      author:
                        _links:
                          lock:
                            href: "/api/v3/users/1/lock"
                            method: post
                            title: Set lock on admin
                          self:
                            href: "/api/v3/users/1"
                            title: OpenProject Admin
                          showUser:
                            href: "/users/1"
                            type: text/html
                          updateImmediately:
                            href: "/api/v3/users/1"
                            method: patch
                            title: Update admin
                        _type: User
                        admin: true
                        avatar: ''
                        createdAt: '2015-03-20T12:56:52.850Z'
                        email:
                        firstName: OpenProject
                        id: 1
                        identityUrl:
                        lastName: Admin
                        login: admin
                        name: OpenProject Admin
                        status: active
                        updatedAt: '2018-05-29T13:57:44.604Z'
                      container:
                        _links:
                          addAttachment:
                            href: "/api/v3/posts/150/attachments"
                            method: post
                          attachments:
                            href: "/api/v3/posts/150/attachments"
                          project:
                            href: "/api/v3/projects/12"
                            title: Demo project
                          self:
                            href: "/api/v3/posts/150"
                        _type: Post
                        id: 150
                        subject: sfsdfsdfsdfsdf
                    _links:
                      author:
                        href: "/api/v3/users/1"
                        title: OpenProject Admin
                      container:
                        href: "/api/v3/posts/150"
                        title: sfsdfsdfsdfsdf
                      delete:
                        href: "/api/v3/attachments/377"
                        method: delete
                      downloadLocation:
                        href: "/api/v3/attachments/377/content"
                      self:
                        href: "/api/v3/attachments/377"
                        title: 200.gif
                    _type: Attachment
                    status: uploaded
                    contentType: image/gif
                    createdAt: '2018-06-01T07:53:36.831Z'
                    description:
                      format: plain
                      html: ''
                      raw: ''
                    digest:
                      algorithm: md5
                      hash: 7ac9c97ef73d47127f590788b84c0c1c
                    fileName: some.gif
                    fileSize: 3521772
                    id: 377
          description: Created
          headers: {}
        '400':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
                    message: The request could not be parsed as JSON.
          description: Returned if the `metadata` part contains unparsable JSON.
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to delete this attachment.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit messages

            *Note that you will only receive this error, if you are at least allowed to see the wiki page*
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the post does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view messages

            *Note: A client without sufficient permissions shall not be able to test for the existence of a post.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: File is too large (maximum size is 5242880 Bytes).
          description: |-
            Returned if the client tries to send an invalid attachment.
            Reasons are:

            * Omitting one of the required parts (`metadata` or `file`)

            * Sending metadata or file parts in an invalid format

            * Omitting the file name (`fileName` property of metadata part)

            * Sending a file that is too large
          headers: {}
      tags:
      - Attachments
      description: Adds an attachment with the post as its container.
      operationId: Add_attachment_to_post
      summary: Add attachment to post
  "/api/v3/posts/{id}/attachments/prepare":
    post:
      summary: Prepare a direct attachment upload for a post
      operationId: prepare_post_attachment_upload
      tags:
      - Attachments
      description: |-
        Prepares a direct upload of an attachment for the given forum post, to be performed by the
        client without the file content passing through the OpenProject server. See
        `POST /api/v3/attachments/prepare` for a detailed description of the three-step flow this
        endpoint is the first step of.

        Unlike `POST /api/v3/attachments/prepare`, the resulting pending attachment is immediately
        associated with this post as its container.
      parameters:
      - name: id
        description: ID of the post to receive the attachment
        example: 1
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - metadata
              properties:
                metadata:
                  type: string
                  contentMediaType: application/json
                  contentSchema:
                    "$ref": "#/components/schemas/AttachmentPrepareUploadWriteModel"
                  description: |-
                    A **single** part, named `metadata`, whose value is a *JSON-encoded string*
                    conforming to the schema referenced above (see the *Model* tab for its
                    properties) - it must **not** be split into separate `fileName`, `fileSize`, ...
                    form fields. No file content is sent with this request.
                  example: '{"fileName":"cat.png","fileSize":24,"contentType":"image/png"}'
            encoding:
              metadata:
                contentType: application/json
      responses:
        '201':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/AttachmentUploadModel"
        '400':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
                message: The request could not be parsed as JSON.
          description: |-
            Returned if the client sends a not understandable request. Reasons include:

            * Omitting the `metadata` part

            * sending unparsable JSON in the metadata part
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to add attachments to this post.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit messages

            *Note that you will only receive this error, if you are at least allowed to see the post.*
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the post does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view messages

            *Note: A client without sufficient permissions shall not be able to test for the existence of a post.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                direct uploads not available:
                  description: Returned if the OpenProject instance is not configured
                    for direct uploads.
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Direct file upload is not available due to a system configuration
                      issue. Please contact your administrator.
                missing file name:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: File can't be blank.
          description: |-
            Returned if the client tries to prepare an invalid attachment upload.
            Reasons are:

            * Omitting the file name (`fileName` property of metadata part)

            * Omitting the file size (`fileSize` property of metadata part)

            * The instance is not configured for direct uploads
  "/api/v3/principals":
    get:
      summary: List principals
      operationId: list_principals
      tags:
      - Principals
      description: |-
        List all principals. The client can choose to filter the principals similar to how work packages are filtered. In
        addition to the provided filters, the server will reduce the result set to only contain principals who are members
        in projects the client is allowed to see.
      parameters:
      - name: filters
        description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint.
          Currently supported filters are:

          - type: filters principals by their type (*User*, *Group*, *PlaceholderUser*).
          - member: filters principals by the projects they are members in.
          - name: filters principals by the user or group name.
          - any_name_attribute: filters principals by the user or group first- and last name, email or login.
          - status: filters principals by their status number (active = *1*, registered = *2*, locked = *3*, invited = *4*)
        in: query
        required: false
        schema:
          type: string
        example: '[{ "type": { "operator": "=", "values": ["User"] } }]'
      - name: select
        description: Comma separated list of properties to include.
        in: query
        required: false
        schema:
          type: string
        example: total,elements/name,elements/self,self
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/PrincipalCollectionModel"
        '400':
          description: Returned if the client sends invalid request parameters e.g.
            filters
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
                message: Filters Invalid filter does not exist.
  "/api/v3/priorities":
    get:
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                simple priority collection:
                  "$ref": "#/components/examples/PriorityCollection"
              schema:
                "$ref": "#/components/schemas/PriorityCollectionModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to see the priorities.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** view work package (on any project)
          headers: {}
      tags:
      - Priorities
      description: ''
      operationId: List_all_Priorities
      summary: List all Priorities
  "/api/v3/priorities/{id}":
    get:
      parameters:
      - description: Priority id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _links:
                      self:
                        href: "/api/v3/priorities/1"
                        title: Low
                    _type: Priority
                    id: 1
                    isActive: true
                    isDefault: false
                    name: Low
                    position: 1
              schema:
                "$ref": "#/components/schemas/PriorityModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to see this priority.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** view work package (on any project)
          headers: {}
      tags:
      - Priorities
      description: ''
      operationId: View_Priority
      summary: View Priority
  "/api/v3/programs":
    get:
      summary: List programs
      operationId: list_programs
      tags:
      - Programs
      description: Returns a collection of programs. The collection can be filtered
        via query parameters similar to how work packages are filtered. In addition
        to the provided filter, the result set is always limited to only contain programs
        the client is allowed to see.
      parameters:
      - name: filters
        schema:
          type: string
        in: query
        required: false
        description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint.
          Currently supported filters are:

          + active: based on the active property of the program
          + ancestor: filters programs by their ancestor. A program is not considered to be its own ancestor.
          + available_project_attributes: filters programs based on the activated project attributes.
          + created_at: based on the time the program was created
          + favorited: based on the favorited property of the program
          + id: based on programs' id.
          + latest_activity_at: based on the time the last activity was registered on a program.
          + name_and_identifier: based on both the name and the identifier.
          + parent_id: filters programs by their parent.
          + principal: based on members of the program.
          + project_phase_any: based on the project phases active in a program.
          + project_status_code: based on status code of the program
          + storage_id: filters programs by linked storages
          + storage_url: filters programs by linked storages identified by the host url
          + type_id: based on the types active in a program.
          + user_action: based on the actions the current user has in the program.
          + visible: based on the visibility for the user (id) provided as the filter value. This filter is useful for admins to identify the programs visible to a user.

          There might also be additional filters based on the custom fields that have been configured.

          Each defined lifecycle step will also define a filter in this list endpoint. Given that the elements are not
          static but rather dynamically created on each OpenProject instance, a list cannot be provided. Those filters follow the schema:
          + project_start_gate_[id]: a filter on a project phase's start gate active in a program. The id is the id of the phase the gate belongs to.
          + project_finish_gate_[id]: a filter on a project phase's finish gate active in a program. The id is the id of the phase the gate belongs to.
          + project_phase_[id]: a filter on a project phase active in a program. The id is the id of the phase queried for.
        example: '[{ "ancestor": { "operator": "=", "values": ["1"] } }]'
      - name: sortBy
        schema:
          type: string
        in: query
        required: false
        description: |-
          JSON specifying sort criteria.
          Currently supported orders are:

          + id
          + name
          + typeahead (sorting by hierarchy and name)
          + created_at
          + public
          + latest_activity_at
          + required_disk_space

          There might also be additional orders based on the custom fields that have been configured.
        example: '[["id", "asc"]]'
      - name: select
        schema:
          type: string
        in: query
        required: false
        description: Comma separated list of properties to include.
        example: total,elements/identifier,elements/name
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ProgramCollectionModel"
              examples:
                simple program collection:
                  "$ref": "#/components/examples/ProgramCollection"
        '400':
          description: Returned if the client sends invalid request parameters e.g.
            filters
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
                message: Filters Invalid filter does not exist.
  "/api/v3/programs/{id}":
    get:
      parameters:
      - description: Program id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ProgramModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the program does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** any permission in the program

            *Note: A client without sufficient permissions shall not be able to test for the existence of a program.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
      tags:
      - Programs
      description: ''
      operationId: View_program
      summary: View program
    patch:
      parameters:
      - description: Program id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProjectWriteModel"
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ProgramModel"
              examples:
                with custom fields:
                  "$ref": "#/components/examples/Program"
          description: OK
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit project for the program to be altered
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the program does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view project

            *Note: A client without sufficient permissions shall not be able to test for the existence of
            a version. That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _embedded:
                      details:
                        attribute: name
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Name can't be blank.
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
          headers: {}
      tags:
      - Programs
      description: Updates the given program by applying the attributes provided in
        the body.
      operationId: Update_Program
      summary: Update Program
    delete:
      parameters:
      - description: Program id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: |-
            Returned if the program was successfully deleted. There is currently no endpoint to query for the actual deletion status.
            Such an endpoint _might_ be added in the future.
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** admin
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the program does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** any permission in the program

            *Note: A client without sufficient permissions shall not be able to test for the existence of
            a version. That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _embedded:
                      details:
                        attribute: base
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Work packages in non descendant projects reference versions
                      of the program or its descendants.
          description: |-
            Returned if the program cannot be deleted. This can happen when there are still references to the program in other workspaces
            that need to be severed at first.
          headers: {}
      tags:
      - Programs
      description: |-
        Deletes the program permanently. As this is a lengthy process, the actual deletion is carried out asynchronously.
        So the program might exist well after the request has returned successfully. To prevent unwanted changes to
        the program scheduled for deletion, it is archived at once.
      operationId: Delete_Program
      summary: Delete Program
  "/api/v3/programs/{id}/form":
    post:
      parameters:
      - description: Program id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
            examples:
              with custom fields:
                "$ref": "#/components/examples/ProgramBody"
              empty:
                description: Empty request to get the form initially in order to start
                  the guided update of a program
                value: {}
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ProjectFormModel"
          description: OK
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit workspace in the program
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
      tags:
      - Programs
      description: ''
      operationId: Program_update_form
      summary: Program update form
  "/api/v3/project_phases/{id}":
    get:
      summary: Get a project phase
      operationId: get_project_phase
      tags:
      - Project Phases
      description: |-
        Gets a project phase resource. This resource contains an instance of a ProjectPhaseDefinition within a project which can
        then have project specific dates.
      parameters:
      - name: id
        description: Project phase id
        in: path
        required: true
        schema:
          type: integer
        example: 1337
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ProjectPhaseModel"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the project phase does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view project phase
  "/api/v3/project_phase_definitions":
    get:
      summary: List project phase definitions
      operationId: list_project_phase_definitions
      tags:
      - Project Phase Definitions
      description: |-
        Returns a collection of all project phase definitions.
        The result set is always limited to only contain project phase definitions the client is allowed to see.
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ProjectPhaseDefinitionCollectionModel"
        '400':
          description: Returned if the client sends invalid request parameters e.g.
            filters
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
                message: Filters Invalid filter does not exist.
  "/api/v3/project_phase_definitions/{id}":
    get:
      summary: Get a project phase definition
      operationId: get_project_phase_definition
      tags:
      - Project Phase Definitions
      description: "Gets a project phase definition resource. This resource is part
        of the abstract definition of a project life\ncycle shaping the phases of
        a project. "
      parameters:
      - name: id
        description: Project phase definition id
        in: path
        required: true
        schema:
          type: integer
        example: 1337
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ProjectPhaseDefinitionModel"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the user does not have permission to see project phases.

            **Required permission:** view project phase OR select project phase
  "/api/v3/project_profiles/{code}":
    get:
      summary: Find a project profile by code
      operationId: get_project_profile_by_code
      tags:
      - Project Profiles
      description: |-
        Looks up a TH project profile joined to an existing project. The `type_id` query parameter is
        required, but the current implementation matches only `code`; it does not filter by `type_id`.
        If multiple profiles share a code, the first matching record is returned.

        A code with no matching profile returns an empty, unpersisted profile with HTTP 200, empty `code` and `name`,
        and `typeId: 0`. Its `id`, `projectId`, and `projectName` are omitted.

        This endpoint applies the API's authentication rules without an additional project visibility
        or project-profile permission check. The generated self link uses the profile's numeric ID,
        while this endpoint looks up a code; use the requested code and `type_id` for subsequent lookups.
      parameters:
      - name: code
        in: path
        required: true
        description: Project code in the upstream PLM system.
        schema:
          type: string
        example: P-2030-001
      - name: type_id
        in: query
        required: true
        description: PLM space type. Required by parameter validation, but currently
          not used to filter profiles.
        schema:
          type: integer
        example: 2
      responses:
        '200':
          description: A matching profile, or an empty profile if no match exists.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ProjectProfileModel"
              examples:
                found:
                  value:
                    _type: ProjectProfile
                    id: 7
                    code: P-2030-001
                    name: Example project
                    typeId: 2
                    projectId: 42
                    projectName: Example project
                    _links:
                      self:
                        href: "/api/v3/project_profiles/7"
                        title: Example project
                notFound:
                  value:
                    _type: ProjectProfile
                    code: ''
                    name: ''
                    typeId: 0
                    _links:
                      self:
                        href: "/api/v3/project_profiles/"
                        title: ''
        '400':
          description: Returned if the required `type_id` parameter is missing.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '401':
          description: Returned if authentication is required and the client is not
            authenticated, or credentials are invalid.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/project_storages":
    get:
      summary: Gets a list of project storages
      operationId: list_project_storages
      tags:
      - File Links
      description: Gets a collection of all project storages that meet the provided
        filters and the user has permission to see them.
      parameters:
      - name: filters
        in: query
        required: false
        schema:
          default: "[]"
          type: string
        description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/)
          endpoint. Currently supported filters are:

          - project_id
          - storage_id
          - storage_url
        example: '[{ "project_id": { "operator": "=", "values": ["42"] }}, { "storage_id":
          { "operator": "=", "values": ["1337"] }}]'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ProjectStorageCollectionModel"
        '400':
          description: Returned if any given filter is invalid.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
                message: The query parameter 'filters' is missing or malformed.
  "/api/v3/project_storages/{id}":
    get:
      summary: Gets a project storage
      operationId: get_project_storage
      tags:
      - File Links
      description: |-
        Gets a project storage resource. This resource contains all data that is applicable on the relation between a
        storage and a project.
      parameters:
      - name: id
        description: Project storage id
        in: path
        required: true
        schema:
          type: integer
        example: 1337
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ProjectStorageModel"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the project storage does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view file links
  "/api/v3/project_storages/{id}/open":
    get:
      summary: Open the project storage
      operationId: open_project_storage
      tags:
      - File Links
      description: |-
        Gets a redirect to the location of the project storage's remote origin. If the project storage has a project
        folder, it is opened at this location. If not, the storage root is opened.
      parameters:
      - name: id
        description: Project storage id
        in: path
        required: true
        schema:
          type: integer
        example: 1337
      responses:
        '303':
          description: Redirect
          headers:
            Location:
              schema:
                type: string
                format: uri
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                message: You are not authorized to access this resource.
          description: Returned if the authorization token of the current user grants
            no permission to access the remote storage.
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the project storage does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view file links
  "/api/v3/projects":
    get:
      summary: List projects
      operationId: list_projects
      tags:
      - Projects
      description: |-
        Returns a collection of projects. The collection can be filtered via query parameters similar to how work packages are filtered. In addition to the provided filter, the result set is always limited to only contain projects the client is allowed to see.
        Prior to OpenProject 17.0, only projects existed and the concept of workspaces wasn't implemented in the API. With 17.0 the other workspace types (program and portfolio) exist and will be returned alongside projects by this endpoint. This might surprise typed clients.
      parameters:
      - name: filters
        schema:
          type: string
        in: query
        required: false
        description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint.
          Currently supported filters are:

          + active: based on the active property of the project
          + ancestor: filters projects by their ancestor. A project is not considered to be its own ancestor.
          + available_project_attributes: filters projects based on the activated project project attributes.
          + created_at: based on the time the project was created
          + favorited: based on the favorited property of the project
          + id: based on projects' id.
          + latest_activity_at: based on the time the last activity was registered on a project.
          + name_and_identifier: based on both the name and the identifier.
          + parent_id: filters projects by their parent.
          + principal: based on members of the project.
          + project_phase_any: based on the project phases active in a project.
          + project_status_code: based on status code of the project
          + storage_id: filters projects by linked storages
          + storage_url: filters projects by linked storages identified by the host url
          + type_id: based on the types active in a project.
          + user_action: based on the actions the current user has in the project.
          + visible: based on the visibility for the user (id) provided as the filter value. This filter is useful for admins to identify the projects visible to a user.

          There might also be additional filters based on the custom fields that have been configured.

          Each defined lifecycle step will also define a filter in this list endpoint. Given that the elements are not
          static but rather dynamically created on each OpenProject instance, a list cannot be provided. Those filters follow the schema:
          + project_start_gate_[id]: a filter on a project phase's start gate active in a project. The id is the id of the phase the gate belongs to.
          + project_finish_gate_[id]: a filter on a project phase's finish gate active in a project. The id is the id of the phase the gate belongs to.
          + project_phase_[id]: a filter on a project phase active in a project. The id is the id of the phase queried for.
        example: '[{ "ancestor": { "operator": "=", "values": ["1"] } }]'
      - name: sortBy
        schema:
          type: string
        in: query
        required: false
        description: |-
          JSON specifying sort criteria.
          Currently supported orders are:

          + id
          + name
          + typeahead (sorting by hierarchy and name)
          + created_at
          + public
          + latest_activity_at
          + required_disk_space

          There might also be additional orders based on the custom fields that have been configured.
        example: '[["id", "asc"]]'
      - name: select
        schema:
          type: string
        in: query
        required: false
        description: Comma separated list of properties to include.
        example: total,elements/identifier,elements/name
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ProjectCollectionModel"
              examples:
                simple project collection:
                  "$ref": "#/components/examples/ProjectCollection"
        '400':
          description: Returned if the client sends invalid request parameters e.g.
            filters
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
                message: Filters Invalid filter does not exist.
    post:
      summary: Create project
      operationId: create_project
      tags:
      - Projects
      description: |-
        Creates a new project, applying the attributes provided in the body.

        You can use the form and schema to be retrieve the valid attribute values and by that be guided towards successful creation.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProjectWriteModel"
      responses:
        '201':
          description: Created
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ProjectModel"
              examples:
                with custom fields:
                  "$ref": "#/components/examples/Project"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** add project which is a global permission
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _embedded:
                  details:
                    attribute: name
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: Name can't be blank.
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
  "/api/v3/projects/form":
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
            examples:
              with custom fields:
                "$ref": "#/components/examples/ProjectBody"
              empty:
                description: Empty request to get the form initially in order to start
                  the guided creation of a project
                value: {}
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                type: object
              examples:
                response:
                  value:
                    _embedded:
                      payload:
                        _links:
                          customField26:
                            href:
                            title:
                          customField31:
                            href:
                            title:
                          parent:
                            href:
                          status:
                            href:
                        active: true
                        customField30:
                        customField34:
                        customField35: Text custom field value
                        customField41:
                          format: markdown
                          html: ''
                          raw: ''
                        customField42:
                        description:
                          format: markdown
                          html: ''
                          raw:
                        identifier: new_project_identifier
                        name: New project name
                        public: false
                        statusExplanation:
                          format: markdown
                          html: "<p></p>"
                          raw:
                      schema:
                        _dependencies: []
                        _links: {}
                        _type: Schema
                        active:
                          hasDefault: true
                          name: Active
                          required: true
                          type: Boolean
                          writable: true
                        createdAt:
                          hasDefault: false
                          name: Created on
                          required: true
                          type: DateTime
                          writable: false
                        customField26:
                          _links:
                            allowedValues:
                              href: "/api/v3/principals?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22%21%22%2C%22values%22%3A%5B%220%22%2C%223%22%5D%7D%7D%2C%7B%22type%22%3A%7B%22operator%22%3A%22%3D%22%2C%22values%22%3A%5B%22User%22%5D%7D%7D%2C%7B%22member%22%3A%7B%22operator%22%3A%22%3D%22%2C%22values%22%3A%5B%22%22%5D%7D%7D%5D&pageSize=0"
                          hasDefault: false
                          location: _links
                          name: Project user
                          required: false
                          type: User
                          visibility: default
                          writable: true
                        customField30:
                          hasDefault: false
                          name: some project cf
                          required: false
                          type: Integer
                          visibility: default
                          writable: true
                        customField31:
                          _embedded:
                            allowedValues:
                            - _links:
                                self:
                                  href: "/api/v3/custom_options/513"
                                  title: abc
                              _type: CustomOption
                              id: 513
                              value: abc
                            - _links:
                                self:
                                  href: "/api/v3/custom_options/514"
                                  title: def
                              _type: CustomOption
                              id: 514
                              value: def
                            - _links:
                                self:
                                  href: "/api/v3/custom_options/515"
                                  title: ghi
                              _type: CustomOption
                              id: 515
                              value: ghi
                          _links:
                            allowedValues:
                            - href: "/api/v3/custom_options/513"
                              title: abc
                            - href: "/api/v3/custom_options/514"
                              title: def
                            - href: "/api/v3/custom_options/515"
                              title: ghi
                          hasDefault: false
                          location: _links
                          name: list project cf
                          required: false
                          type: CustomOption
                          visibility: default
                          writable: true
                        customField34:
                          hasDefault: false
                          name: Bool Project CF
                          required: false
                          type: Boolean
                          visibility: default
                          writable: true
                        customField35:
                          hasDefault: false
                          name: text project cf
                          required: true
                          type: String
                          visibility: default
                          writable: true
                        customField41:
                          hasDefault: false
                          name: Long text project cf
                          required: false
                          type: Formattable
                          visibility: default
                          writable: true
                        customField42:
                          hasDefault: false
                          name: Date project cf
                          required: false
                          type: Date
                          visibility: default
                          writable: true
                        description:
                          hasDefault: false
                          name: Description
                          required: false
                          type: Formattable
                          writable: true
                        id:
                          hasDefault: false
                          name: ID
                          required: true
                          type: Integer
                          writable: false
                        identifier:
                          hasDefault: false
                          maxLength: 100
                          minLength: 1
                          name: Identifier
                          required: true
                          type: String
                          writable: true
                        name:
                          hasDefault: false
                          maxLength: 255
                          minLength: 1
                          name: Name
                          required: true
                          type: String
                          writable: true
                        parent:
                          _links:
                            allowedValues:
                              href: "/api/v3/projects/available_parent_projects"
                          hasDefault: false
                          location: _links
                          name: Subproject of
                          required: false
                          type: Project
                          visibility: default
                          writable: true
                        public:
                          hasDefault: false
                          name: Public
                          required: true
                          type: Boolean
                          writable: true
                        status:
                          _links:
                            allowedValues:
                            - href: "/api/v3/project_statuses/on_track"
                              title: On track
                            - href: "/api/v3/project_statuses/at_risk"
                              title: At risk
                            - href: "/api/v3/project_statuses/off_track"
                              title: Off track
                            - href: "/api/v3/project_statuses/on_pause"
                              title: On pause
                          hasDefault: true
                          name: Status
                          required: false
                          type: ProjectStatus
                          writable: true
                        statusExplanation:
                          hasDefault: false
                          name: Status explanation
                          required: false
                          type: Formattable
                          writable: true
                        updatedAt:
                          hasDefault: false
                          name: Updated on
                          required: true
                          type: DateTime
                          writable: false
                      validationErrors:
                        identifier:
                          _embedded:
                            details:
                              attribute: identifier
                          _type: Error
                          errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                          message: Identifier has already been taken.
                    _links:
                      self:
                        href: "/api/v3/projects/form"
                        method: post
                      validate:
                        href: "/api/v3/projects/form"
                        method: post
                    _type: Form
          description: OK
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** add project which is a global permission
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
      tags:
      - Projects
      description: ''
      operationId: Project_create_form
      summary: Project create form
  "/api/v3/projects/schema":
    get:
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _dependencies: []
                    _attributeGroups:
                    - _type: ProjectFormCustomFieldSection
                      name: Project Details
                      attributes:
                      - customField30
                      - customField34
                    - _type: ProjectFormCustomFieldSection
                      name: Budget Information
                      attributes:
                      - customField31
                      - customField32
                      - customField35
                    _links:
                      self:
                        href: "/api/v3/projects/schema"
                    _type: Schema
                    active:
                      hasDefault: true
                      name: Active
                      required: true
                      type: Boolean
                      writable: true
                    createdAt:
                      hasDefault: false
                      name: Created on
                      required: true
                      type: DateTime
                      writable: false
                    customField30:
                      hasDefault: false
                      name: Integer project custom field
                      required: false
                      type: Integer
                      visibility: default
                      writable: true
                    customField31:
                      _links: {}
                      hasDefault: false
                      location: _links
                      name: List project custom field
                      required: false
                      type: CustomOption
                      visibility: default
                      writable: true
                    customField32:
                      _links: {}
                      hasDefault: false
                      location: _links
                      name: Version project custom field
                      required: false
                      type: Version
                      visibility: default
                      writable: true
                    customField34:
                      hasDefault: false
                      name: Boolean project custom field
                      required: false
                      type: Boolean
                      visibility: default
                      writable: true
                    customField35:
                      hasDefault: false
                      name: Text project custom field
                      required: true
                      type: String
                      visibility: default
                      writable: true
                    description:
                      hasDefault: false
                      name: Description
                      required: false
                      type: Formattable
                      writable: true
                    id:
                      hasDefault: false
                      name: ID
                      required: true
                      type: Integer
                      writable: false
                    identifier:
                      hasDefault: false
                      maxLength: 100
                      minLength: 1
                      name: Identifier
                      required: true
                      type: String
                      writable: true
                    name:
                      hasDefault: false
                      maxLength: 255
                      minLength: 1
                      name: Name
                      required: true
                      type: String
                      writable: true
                    parent:
                      _links: {}
                      hasDefault: false
                      location: _links
                      name: Subproject of
                      required: false
                      type: Project
                      visibility: default
                      writable: true
                    public:
                      hasDefault: false
                      name: Public
                      required: true
                      type: Boolean
                      writable: true
                    status:
                      _links:
                        allowedValues:
                        - href: "/api/v3/project_statuses/on_track"
                          title: On track
                        - href: "/api/v3/project_statuses/at_risk"
                          title: At risk
                        - href: "/api/v3/project_statuses/off_track"
                          title: Off track
                        - href: "/api/v3/project_statuses/on_pause"
                          title: On pause
                      hasDefault: true
                      name: Status
                      required: false
                      type: ProjectStatus
                      writable: true
                    statusExplanation:
                      hasDefault: false
                      name: Status explanation
                      required: false
                      type: Formattable
                      writable: true
                    updatedAt:
                      hasDefault: false
                      name: Updated on
                      required: true
                      type: DateTime
                      writable: false
              schema:
                "$ref": "#/components/schemas/Workspaces_schemaModel"
          description: OK
          headers: {}
      tags:
      - Projects
      description: |-
        Provides the schema describing a project resource.
        This endpoint is deprecated. As projects are workspaces, an equivalent schema can be found fetching `/api/v3/workspaces/schema`.
      operationId: View_project_schema
      summary: View project schema
  "/api/v3/projects/{id}":
    delete:
      parameters:
      - description: Project id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: |-
            Returned if the project was successfully deleted. There is currently no endpoint to query for the actual deletion status.
            Such an endpoint _might_ be added in the future.
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** admin
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the project does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** any permission in the project

            *Note: A client without sufficient permissions shall not be able to test for the existence of
            a version. That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _embedded:
                      details:
                        attribute: base
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Work packages in non descendant projects reference versions
                      of the project or its descendants.
          description: |-
            Returned if the project cannot be deleted. This can happen when there are still references to the project in other workspaces
            that need to be severed at first.
          headers: {}
      tags:
      - Projects
      description: |-
        Deletes the project permanently. As this is a lengthy process, the actual deletion is carried out asynchronously.
        So the project might exist well after the request has returned successfully. To prevent unwanted changes to
        the project scheduled for deletion, it is archived at once.
      operationId: Delete_Project
      summary: Delete Project
    get:
      parameters:
      - description: Project id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                with custom fields:
                  "$ref": "#/components/examples/Project"
              schema:
                "$ref": "#/components/schemas/ProjectModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the project does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view project

            *Note: A client without sufficient permissions shall not be able to test for the existence of a project.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
      tags:
      - Projects
      description: ''
      operationId: View_project
      summary: View project
    patch:
      parameters:
      - description: Project id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProjectWriteModel"
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ProjectModel"
              examples:
                with custom fields:
                  "$ref": "#/components/examples/Project"
          description: OK
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit project for the project to be altered
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the project does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view project

            *Note: A client without sufficient permissions shall not be able to test for the existence of
            a version. That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _embedded:
                      details:
                        attribute: name
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Name can't be blank.
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
          headers: {}
      tags:
      - Projects
      description: Updates the given project by applying the attributes provided in
        the body.
      operationId: Update_Project
      summary: Update Project
  "/api/v3/projects/{id}/form":
    post:
      parameters:
      - description: Project id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
            examples:
              with custom fields:
                "$ref": "#/components/examples/ProjectBody"
              empty:
                description: Empty request to get the form initially in order to start
                  the guided update of a project
                value: {}
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ProjectFormModel"
          description: OK
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit projects in the project
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
      tags:
      - Projects
      description: ''
      operationId: Project_update_form
      summary: Project update form
  "/api/v3/projects/{id}/copy":
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProjectCopyWriteModel"
            example:
              name: My copied project
              identifier: my-copied-project
              _meta:
                copyWorkPackages: true
                copyWiki: false
                sendNotifications: false
      parameters:
      - description: Project id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '302':
          description: Returned if the request is successful. It will redirect to
            the job statuses API with the backend job that got created. You can query
            that endpoint to check the status of the copy, and eventually get the
            created project.
          headers:
            Location:
              description: The relative URL of the background job's status resource.
              schema:
                type: string
                format: uri-reference
              example: "/api/v3/job_statuses/6d0b09f0-1fbe-4e4c-a59e-748e08c263a7"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** copy projects in the source project
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _embedded:
                      details:
                        attribute: name
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Name can't be blank.
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
          headers: {}
      tags:
      - Projects
      description: |-
        Copies the source project using the supplied attributes for the new project.
        The `_meta` properties select which associated resources to copy and whether to send notifications.
      operationId: Create_project_copy
      summary: Create project copy
  "/api/v3/projects/{id}/copy/form":
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProjectCopyWriteModel"
      parameters:
      - description: Project id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ProjectCopyFormModel"
          description: OK
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** copy projects in the source project
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
      tags:
      - Projects
      description: ''
      operationId: Project_copy_form
      summary: Project copy form
  "/api/v3/project_statuses/{id}":
    get:
      parameters:
      - description: Project status id
        example: on_track
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _links:
                      self:
                        href: "/api/v3/project_statuses/on_track"
                    _type: ProjectStatus
                    id: on_track
                    name: On track
              schema:
                "$ref": "#/components/schemas/View_project_statusModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: Returned if the project status does not exist.
          headers: {}
      tags:
      - Projects
      description: ''
      operationId: View_project_status
      summary: View project status
  "/api/v3/projects/available_parent_projects":
    get:
      parameters:
      - description: JSON specifying filter conditions.
        example: '[{ "ancestor": { "operator": "=", "values": ["1"] } }]'
        in: query
        name: filters
        required: false
        schema:
          type: string
      - description: The id or identifier of the project the parent candidate is determined
          for
        example: '123'
        in: query
        name: of
        required: false
        schema:
          type: string
      - description: |-
          The workspace type of the new project the parent candidate is determined for. Ignored when `of` parameter is provided.
          Note that while 'portfolio' is supported as a type (since it is a type of Workspace), the endpoint will currently always return an empty resultset as portfolios cannot have parents.
        example: program
        in: query
        name: workspace_type
        required: false
        schema:
          type: string
          enum:
          - project
          - program
          - portfolio
      - description: |-
          JSON specifying sort criteria.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint and allows all the filters and sortBy supported by the project list endpoint.
        example: '[["id", "asc"]]'
        in: query
        name: sortBy
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          categories:
                            href: "/api/v3/projects/6/categories"
                          createWorkPackage:
                            href: "/api/v3/projects/6/work_packages/form"
                            method: post
                          createWorkPackageImmediate:
                            href: "/api/v3/projects/6/work_packages"
                            method: post
                          self:
                            href: "/api/v3/projects/6"
                            title: A project
                          status:
                            href: "/api/v3/project_statuses/on_track"
                            title: On track
                          versions:
                            href: "/api/v3/projects/6/versions"
                        _type: Project
                        active: true
                        createdAt: '2015-07-06T13:28:14+00:00'
                        description:
                          format: markdown
                          html: "<p>Lorem <strong>ipsum</strong> dolor sit amet</p>"
                          raw: Lorem **ipsum** dolor sit amet
                        id: 6
                        identifier: a_project
                        name: A project
                        public: false
                        statusExplanation:
                          format: markdown
                          html: "<p>Everything <strong>fine</strong></p>"
                          raw: Everything **fine**
                        type: Customer Project
                        updatedAt: '2015-10-01T09:55:02+00:00'
                      - _links:
                          categories:
                            href: "/api/v3/projects/14/categories"
                          createWorkPackage:
                            href: "/api/v3/projects/14/work_packages/form"
                            method: post
                          createWorkPackageImmediate:
                            href: "/api/v3/projects/14/work_packages"
                            method: post
                          self:
                            href: "/api/v3/projects/14"
                            title: Another project
                          status:
                            href: "/api/v3/project_statuses/on_track"
                            title: On track
                          versions:
                            href: "/api/v3/projects/14/versions"
                        _type: Project
                        active: true
                        createdAt: '2016-02-29T12:50:20+00:00'
                        description:
                          format: markdown
                          html: ''
                          raw: ''
                        id: 14
                        identifier: another_project
                        name: Another project
                        public: true
                        statusExplanation:
                          format: markdown
                          html: "<p>Everything super <strong>fine</strong></p>"
                          raw: Everything super **fine**
                        type:
                        updatedAt: '2016-02-29T12:50:20+00:00'
                    _links:
                      self:
                        href: "/api/v3/projects/available_parent_projects?of=123"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/List_available_parent_project_candidatesModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit project in a project or the global add project permission
          headers: {}
      tags:
      - Projects
      description: |-
        Lists projects which can become parent to another project. Only sound candidates are returned.
        For instance a project cannot become parent of itself or its children.

        To specify the project for which a parent is queried for, the `of` parameter can be provided. If no `of`
        parameter is provided, a new project is assumed. Then, the check for the hierarchy is omitted as a new project cannot be
        part of a hierarchy yet, instead `workspace_type` parameter can be passed defining it for new project.

        Candidates can be filtered. Most commonly one will want to filter by name or identifier.
        You can do this through the `filters` parameter which works just like the work package index.

        For instance to find all parent candidates with "rollout" in their name:

        ```
        ?filters=[{"name_and_identifier":{"operator":"~","values":["rollout"]}}]
        ```
      operationId: List_available_parent_project_candidates
      summary: List available parent project candidates
  "/api/v3/projects/{id}/budgets":
    get:
      parameters:
      - description: Project id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          self:
                            href: "/api/v3/budgets/1"
                            title: Q3 2015
                        _type: Budget
                        id: 1
                        subject: Q3 2015
                      - _links:
                          self:
                            href: "/api/v3/budgets/2"
                            title: Q4 2015
                        _type: Budget
                        id: 2
                        subject: Q4 2015
                    _links:
                      self:
                        href: "/api/v3/projects/1/budgets"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/Budgets_by_ProjectModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to see the budgets of this project.
          description: |-
            Returned if the client does not have sufficient permissions to see the budgets of the given
            project.

            **Required permission:** view work packages **or** view budgets

            *Note that you will only receive this error, if you are at least allowed to see the corresponding project.*
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified project does not exist.
          description: |-
            Returned if either:

            * the project does not exist

            * the client does not have sufficient permissions to see the project

            * the costs module is not enabled on the given project

            **Required permission:** view project

            *Note: A client without sufficient permissions shall not be able to test for the existence of a project.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
      tags:
      - Budgets
      description: ''
      operationId: view_Budgets_of_a_Project
      summary: view Budgets of a Project
  "/api/v3/projects/{id}/activities":
    get:
      summary: List project work package activities
      operationId: list_project_activities
      tags:
      - Activities
      description: |-
        Returns an unpaginated collection of work package journals for the project. This includes
        changes and comments; it is not a feed of all project resource types.

        The parent project must be accessible to the caller. The endpoint does not apply an additional
        work package visibility filter to the project's journals. Both date bounds are optional and
        inclusive; `to_date` is implemented as a cutoff before the start of the following day.
      parameters:
      - name: id
        in: path
        required: true
        description: Project ID or identifier.
        schema:
          type: string
        example: '42'
      - name: from_date
        in: query
        required: false
        description: Include activities created on or after this date. An empty value
          is ignored.
        schema:
          type: string
          format: date
        example: '2030-06-01'
      - name: to_date
        in: query
        required: false
        description: Include activities created on or before this date. An empty value
          is ignored.
        schema:
          type: string
          format: date
        example: '2030-06-30'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ActivityCollectionModel"
        '401':
          description: Returned if authentication is required and the client is not
            authenticated, or credentials are invalid.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '404':
          description: Returned if the project does not exist or is not accessible
            to the caller.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '422':
          description: Returned if a non-empty date is malformed (`PropertyFormatError`).
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/projects/{id}/all_members_assigned_projects":
    get:
      summary: List projects with work assigned to project members
      operationId: list_all_members_assigned_projects
      tags:
      - Projects
      description: |-
        Finds projects containing work packages assigned to any member of the given project.
        Returned projects must allow the caller to view work packages or contain work packages visible
        to the caller. Only projects with status `on_track`, `at_risk`, `off_track`, `not_started`,
        `on_pause`, or no status are included.

        The parent project must be accessible to the caller. The response uses the paginated project
        collection format but always requests the first page with 200 entries, capped by the configured
        API maximum page size. Query parameters such as `offset`, `pageSize`, `filters`, and `sortBy`
        are not forwarded to the collection. Generated pagination links do not change that behavior.
      parameters:
      - name: id
        in: path
        required: true
        description: ID or identifier of the project whose members' assignments are
          examined.
        schema:
          type: string
        example: '42'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ProjectCollectionModel"
        '401':
          description: Returned if authentication is required and the client is not
            authenticated, or credentials are invalid.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '404':
          description: Returned if the parent project does not exist or is not accessible
            to the caller.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/projects/{id}/queries/default":
    get:
      summary: View default query for project
      operationId: View_default_query_for_project
      tags:
      - Queries
      description: |-
        Same as [viewing an existing, persisted Query](https://www.openproject.org/docs/api/endpoints/queries/#list-queries)
        in its response, this resource returns an unpersisted query and by that allows
        to get the default query configuration. The client may also provide additional
        parameters which will modify the default query. The query will already be scoped
        to the project.

        This endpoint is deprecated and replaced by [`/api/v3/workspaces/{id}/queries/default`](https://www.openproject.org/docs/api/endpoints/queries/#view-default-query-for-workspace)
      parameters:
      - description: Id of the project the default query is requested for
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      - name: filters
        description: |-
          JSON specifying filter conditions.
          The filters provided as parameters are not applied to the query but are instead used to override the query's persisted filters.
          All filters also accepted by the work packages endpoint are accepted. If no filter is to be applied, the client should send an empty array (`[]`).
        example: '[{ "assignee": { "operator": "=", "values": ["1", "5"] } }]'
        in: query
        required: false
        schema:
          default: '[{ "status_id": { "operator": "o", "values": null }}]'
          type: string
      - name: offset
        description: Page number inside the queries' result collection of work packages.
        example: 25
        in: query
        required: false
        schema:
          default: 1
          type: integer
      - name: pageSize
        description: Number of elements to display per page for the queries' result
          collection of work packages.
        example: 25
        in: query
        required: false
        schema:
          type: integer
      - name: sortBy
        description: JSON specifying sort criteria. The sort criteria is applied to
          the query's result collection of work packages overriding the query's persisted
          sort criteria.
        example: '[["status", "asc"]]'
        in: query
        required: false
        schema:
          default: '[["id", "asc"]]'
          type: string
      - name: groupBy
        description: The column to group by. The grouping criteria is applied to the
          to the query's result collection of work packages overriding the query's
          persisted group criteria.
        example: status
        in: query
        required: false
        schema:
          type: string
      - name: showSums
        description: Indicates whether properties should be summed up if they support
          it. The showSums parameter is applied to the to the query's result collection
          of work packages overriding the query's persisted sums property.
        example: true
        in: query
        required: false
        schema:
          default: false
          type: boolean
      - name: timestamps
        description: 'Indicates the timestamps to filter by when showing changed attributes
          on work packages. Values can be either ISO8601 dates, ISO8601 durations
          and the following relative date keywords: "oneDayAgo@HH:MM+HH:MM", "lastWorkingDay@HH:MM+HH:MM",
          "oneWeekAgo@HH:MM+HH:MM", "oneMonthAgo@HH:MM+HH:MM". The first "HH:MM" part
          represents the zero paded hours and minutes. The last "+HH:MM" part represents
          the timezone offset from UTC associated with the time. Values older than
          1 day are accepted only with valid Enterprise Token available.

          '
        example: 2023-01-01,P-1Y,PT0S,lastWorkingDay@12:00
        in: query
        required: false
        schema:
          default: PT0S
          type: string
      - name: timelineVisible
        description: Indicates whether the timeline should be shown.
        example: true
        in: query
        required: false
        schema:
          default: false
          type: boolean
      - name: showHierarchies
        description: Indicates whether the hierarchy mode should be enabled.
        example: true
        in: query
        required: false
        schema:
          default: true
          type: boolean
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      results:
                        _embedded:
                          elements:
                          - "<--- shortened for brevity --->"
                        _links:
                          changeSize:
                            href: "/api/v3/workspaces/42/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=%7Bsize%7D&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                            templated: true
                          createWorkPackage:
                            href: "/api/v3/work_packages/form"
                            method: post
                          createWorkPackageImmediate:
                            href: "/api/v3/work_packages"
                            method: post
                          jumpTo:
                            href: "/api/v3/workspaces/42/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=%7Boffset%7D&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                            templated: true
                          self:
                            href: "/api/v3/workspaces/42/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                        _type: WorkPackageCollection
                        count: 30
                        offset: 1
                        pageSize: 2
                        total: 234
                    _links:
                      columns:
                      - href: "/api/v3/queries/columns/id"
                        title: ID
                      - href: "/api/v3/queries/columns/subject"
                        title: Subject
                      - href: "/api/v3/queries/columns/type"
                        title: Type
                      - href: "/api/v3/queries/columns/status"
                        title: Status
                      - href: "/api/v3/queries/columns/priority"
                        title: Priority
                      - href: "/api/v3/queries/columns/assignee"
                        title: Assignee
                      - href: "/api/v3/queries/columns/updated_at"
                        title: Updated on
                      groupBy:
                        href:
                        title:
                      project:
                        href: "/api/v3/projects/42"
                        title: Lorem ipsum project
                      results:
                        href: "/api/v3/workspaces/42/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                      self:
                        href: "/api/v3/workspaces/42/queries/default"
                        title: Default
                      sortBy:
                      - href: "/api/v3/queries/sort_bys/parent-desc"
                        title: Parent (Descending)
                      user:
                        href: "/api/v3/users/1"
                        title: OpenProject Admin
                    _type: Query
                    filters:
                    - _links:
                        filter:
                          href: "/api/v3/queries/filters/status"
                          title: Status
                        operator:
                          href: "/api/v3/queries/operators/o"
                          title: open
                        schema:
                          href: "/api/v3/queries/filter_instance_schemas/status"
                        values: []
                      _type: StatusQueryFilter
                      name: Status
                    name: default
                    public: false
                    showHierarchies: true
                    starred: false
                    sums: false
                    timelineVisible: false
                    timelineZoomLevel: days
              schema:
                "$ref": "#/components/schemas/Default_Query_for_WorkspaceModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions to see the default query.

            **Required permission:** view work packages in the project
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the client does not have sufficient permissions to see the project.

            **Required permission:** any permission in the project
          headers: {}
  "/api/v3/projects/{id}/queries/filter_instance_schemas":
    get:
      parameters:
      - description: Project id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _dependencies:
                        - _type: SchemaDependency
                          dependencies:
                            "/api/v3/queries/operators/!":
                              values:
                                _links: {}
                                hasDefault: false
                                name: Values
                                required: true
                                type: "[]User"
                                writable: true
                            "/api/v3/queries/operators/!*": {}
                            "/api/v3/queries/operators/*": {}
                            "/api/v3/queries/operators/=":
                              values:
                                _links: {}
                                hasDefault: false
                                name: Values
                                required: true
                                type: "[]User"
                                writable: true
                          'on': operator
                        _links:
                          filter:
                            href: "/api/v3/queries/filters/assignee"
                            title: Assignee
                          self:
                            href: "/api/v3/queries/filter_instance_schemas/assignee"
                        _type: QueryFilterInstanceSchema
                        filter:
                          _links: {}
                          hasDefault: false
                          name: Filter
                          required: true
                          type: QueryFilter
                          writable: true
                        name:
                          hasDefault: true
                          name: Name
                          required: true
                          type: String
                          writable: false
                      - _dependencies:
                        - _type: SchemaDependency
                          dependencies:
                            "/api/v3/queries/operators/!":
                              values:
                                _links: {}
                                hasDefault: false
                                name: Values
                                required: true
                                type: "[]User"
                                writable: true
                            "/api/v3/queries/operators/=":
                              values:
                                _links: {}
                                hasDefault: false
                                name: Values
                                required: true
                                type: "[]User"
                                writable: true
                          'on': operator
                        _links:
                          filter:
                            href: "/api/v3/queries/filters/author"
                            title: Author
                          self:
                            href: "/api/v3/queries/filter_instance_schemas/author"
                        _type: QueryFilterInstanceSchema
                        filter:
                          _links: {}
                          hasDefault: false
                          name: Filter
                          required: true
                          type: QueryFilter
                          writable: true
                        name:
                          hasDefault: true
                          name: Name
                          required: true
                          type: String
                          writable: false
                    _links:
                      self:
                        href: "/api/v3/projects/42/queries/filter_instance_schemas"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/Query_Filter_Instance_Schemas_For_WorkspaceModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions to see it.

            **Required permission:** view work package in any project
          headers: {}
      tags:
      - Query Filter Instance Schema
      description: |-
        Returns the list of QueryFilterInstanceSchemas defined for a query
        of the specified project.

        This endpoint is deprecated and replaced by [`/api/v3/workspaces/{id}/queries/filter_instance_schemas`](https://www.openproject.org/docs/api/endpoints/query-filter-instance-schema/#list-query-filter-instance-schemas-for-workspace)
      operationId: List_Query_Filter_Instance_Schemas_for_Project
      summary: List Query Filter Instance Schemas for Project
  "/api/v3/projects/{id}/queries/schema":
    get:
      parameters:
      - description: Project id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                QuerySchema:
                  "$ref": "#/components/examples/QuerySchemaModel"
              schema:
                "$ref": "#/components/schemas/Schema_For_Workspace_QueriesModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: "**Required permission:** view work package in the project"
          headers: {}
      tags:
      - Queries
      description: |-
        Retrieve the schema for project queries.

        This endpoint is deprecated and replaced by ['/api/v3/workspaces/{id}/queries/schema`](https://www.openproject.org/docs/api/endpoints/queries/#view-schema-for-workspace-queries)
      operationId: View_schema_for_project_queries
      summary: View schema for project queries
  "/api/v3/projects/{id}/th_queries/default":
    get:
      summary: View the default TH query for a project
      operationId: get_default_th_query_for_project
      tags:
      - TH Queries
      description: |-
        Returns an unpersisted default query scoped to the project, with work package results in
        `_embedded.results`. Query parameters override the defaults for this response without saving
        a query. The caller must have `view_work_packages` permission in the project.

        Response links use the standard query and work package endpoints; the query self link points
        to `/api/v3/workspaces/{id}/queries/default`.
      parameters:
      - name: id
        in: path
        required: true
        description: Project ID or identifier.
        schema:
          type: string
        example: '42'
      - name: filters
        description: JSON filter conditions replacing the query filters for this request.
          Use [] to remove all filters. Accepts the same filters as the work packages
          endpoint.
        example: '[{ "assignee": { "operator": "=", "values": ["1", "5"] } }]'
        in: query
        required: false
        schema:
          type: string
      - name: offset
        description: Page number inside the queries' result collection of work packages.
        example: 25
        in: query
        required: false
        schema:
          default: 1
          type: integer
      - name: pageSize
        description: Number of elements to display per page for the queries' result
          collection of work packages.
        example: 25
        in: query
        required: false
        schema:
          type: integer
      - name: columns[]
        description: |-
          Selected columns for the table view. Repeat the parameter for every column,
          e.g. `columns[]=type&columns[]=priority`.
        example:
        - type
        - priority
        in: query
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: sortBy
        description: JSON sort criteria for the result work packages, overriding the
          query configuration for this request.
        example: '[["status", "asc"]]'
        in: query
        required: false
        schema:
          type: string
      - name: groupBy
        description: Column used to group the result work packages. An empty value
          clears the grouping.
        example: status
        in: query
        required: false
        schema:
          type: string
      - name: showSums
        description: Whether to calculate sums for properties that support them.
        example: true
        in: query
        required: false
        schema:
          type: boolean
      - name: timestamps
        description: 'Indicates the timestamps to filter by when showing changed attributes
          on work packages. Values can be either ISO8601 dates, ISO8601 durations
          and the following relative date keywords: "oneDayAgo@HH:MM+HH:MM", "lastWorkingDay@HH:MM+HH:MM",
          "oneWeekAgo@HH:MM+HH:MM", "oneMonthAgo@HH:MM+HH:MM". The first "HH:MM" part
          represents the zero paded hours and minutes. The last "+HH:MM" part represents
          the timezone offset from UTC associated with the time, the offset can be
          positive or negative e.g."oneDayAgo@01:00+01:00", "oneDayAgo@01:00-01:00".
          Values older than 1 day are accepted only with valid Enterprise Token available.

          '
        example: 2023-01-01,P-1Y,PT0S,lastWorkingDay@12:00
        in: query
        required: false
        schema:
          type: string
      - name: timelineVisible
        description: Indicates whether the timeline should be shown.
        example: true
        in: query
        required: false
        schema:
          type: boolean
      - name: timelineLabels
        description: Overridden labels in the timeline view
        example: "{}"
        in: query
        required: false
        schema:
          type: string
      - name: highlightingMode
        description: Highlighting mode for the table view.
        example: inline
        in: query
        required: false
        schema:
          type: string
      - name: highlightedAttributes[]
        description: |-
          Highlighted attributes mode for the table view when `highlightingMode` is `inline`.
          Repeat the parameter for every attribute, e.g.
          `highlightedAttributes[]=type&highlightedAttributes[]=priority`.
          When omitted, all highlightable attributes will be returned as `highlightedAttributes`.
        example:
        - type
        - priority
        in: query
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: showHierarchies
        description: Indicates whether the hierarchy mode should be enabled.
        example: true
        in: query
        required: false
        schema:
          type: boolean
      - in: query
        required: false
        name: includeSubprojects
        description: Include work packages from subprojects of the query project.
        schema:
          type: boolean
      - in: query
        required: false
        name: includeAllMembersAssignedProjects
        description: Include projects with work assigned to members of the query project.
          Work package visibility still applies.
        schema:
          type: boolean
      - in: query
        required: false
        name: timelineZoomLevel
        description: Override the timeline zoom level.
        schema:
          type: string
        example: days
      - in: query
        required: false
        name: displayRepresentation
        description: Override the query display representation.
        schema:
          type: string
        example: table
      - in: query
        required: false
        name: select
        description: Comma-separated properties to include in the embedded work package
          results. Nested properties use slash-separated paths.
        schema:
          type: string
        example: id,subject
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/Default_Query_for_WorkspaceModel"
        '400':
          description: Returned if query parameters are malformed or the resulting
            query is invalid.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '401':
          description: Returned if authentication is required and the client is not
            authenticated, or credentials are invalid.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '403':
          description: Returned if the caller lacks view_work_packages permission
            in the project.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '404':
          description: Returned if the project does not exist or is not accessible
            to the caller.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/projects/{id}/work_packages":
    get:
      summary: Get work packages of project
      operationId: Get_Project_Work_Package_Collection
      tags:
      - Work Packages
      description: |-
        Returns the collection of work packages that are related to the given project.
        This endpoint is deprecated and replaced by [`/api/v3/workspaces/{id}/work_packages`](https://www.openproject.org/docs/api/endpoints/work-packages/#get-work-packages-of-workspace)
      parameters:
      - description: Project id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: Page number inside the requested collection.
        example: 25
        in: query
        name: offset
        required: false
        schema:
          default: 1
          type: integer
      - description: Number of elements to display per page.
        example: 25
        in: query
        name: pageSize
        required: false
        schema:
          type: integer
      - description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. If no filter is to be applied, the client should send an empty array (`[]`).
        example: '[{ "type_id": { "operator": "=", "values": ["1", "2"] }}]'
        in: query
        name: filters
        required: false
        schema:
          default: '[{ "status_id": { "operator": "o", "values": null }}]'
          type: string
      - description: |-
          JSON specifying sort criteria.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint.
        example: '[["status", "asc"]]'
        in: query
        name: sortBy
        required: false
        schema:
          default: '[["id", "asc"]]'
          type: string
      - description: The column to group by.
        example: status
        in: query
        name: groupBy
        required: false
        schema:
          type: string
      - description: Indicates whether properties should be summed up if they support
          it.
        example: true
        in: query
        name: showSums
        required: false
        schema:
          default: false
          type: boolean
      - description: Comma separated list of properties to include.
        example: total,elements/subject,elements/id,self
        in: query
        name: select
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/Work_PackagesModel"
          description: OK
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to see the work packages of this project.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** view work packages

            *Note that you will only receive this error, if you are at least allowed to see the corresponding project.*
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified project does not exist.
          description: |-
            Returned if the project does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view project
    post:
      summary: Create work package in project
      operationId: Create_Project_Work_Package
      tags:
      - Work Packages
      description: |-
        When calling this endpoint the client provides a single object, containing at least the properties and links that
        are required, in the body. The required fields of a WorkPackage can be found in its schema, which is embedded in
        the respective form. Note that it is only allowed to provide properties or links supporting the write operation.

        This endpoint is deprecated and replaced by [`/api/v3/workspaces/{id}/work_packages`](https://www.openproject.org/docs/api/endpoints/work-packages/#create-work-package-in-workspace)
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WorkPackageWriteModel"
      parameters:
      - description: Project id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: |-
          Indicates whether change notifications (e.g. via E-Mail) should be sent.
          Note that this controls notifications for all users interested in changes to the work package (e.g. watchers, author and assignee),
          not just the current user.
        example: false
        in: query
        name: notify
        required: false
        schema:
          default: true
          type: boolean
      responses:
        '201':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/WorkPackageModel"
          description: Created
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to add work packages to this project.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** add work packages

            *Note that you will only receive this error, if you are at least allowed to see the corresponding project.*
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified project does not exist.
          description: |-
            Returned if the project does not exist or the client does not have sufficient permissions
            to see it.

            **Required permissions:** view project

            *Note: A client without sufficient permissions shall not be able to test for the existence of a project.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _embedded:
                  details:
                    attribute: Subject
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: The subject might not be blank.
          description: |-
            Returned if:

            * the client tries to write a read-only property

            * a constraint for a property was violated

            * a property was provided in an unreadable format
  "/api/v3/projects/{id}/work_packages/form":
    post:
      summary: Form for creating Work Packages in a Project
      operationId: form_create_work_package_in_project
      tags:
      - Work Packages
      description: |-
        This endpoint allows you to validation a new work package creation body in a specific project. It works similarly
        to the `/api/v3/work_packages/form` endpoint, but already specifies the work package's project in the path, so that
        it does not have to be defined in the request body.

        This endpoint is deprecated and replaced by [`/api/v3/workspaces/{id}/work_packages/form`](https://www.openproject.org/docs/api/endpoints/work-packages/#form-for-creating-work-packages-in-a-workspace)
      parameters:
      - name: id
        description: ID of the project in which the work package will be created
        in: path
        required: true
        schema:
          type: integer
        example: 1
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WorkPackageWriteModel"
            examples:
              Minimal example:
                "$ref": "#/components/examples/WorkPackageCreateOnlySubject"
              Valid example:
                "$ref": "#/components/examples/WorkPackageCreateValid"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/WorkPackageFormModel"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
  "/api/v3/projects/{id}/available_assignees":
    get:
      parameters:
      - description: Project id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          delete:
                            href: "/api/v3/users/1"
                            method: DELETE
                            title: Delete j.sheppard
                          lock:
                            href: "/api/v3/users/1/lock"
                            method: POST
                            title: Set lock on j.sheppard
                          self:
                            href: "/api/v3/users/1"
                            title: John Sheppard - j.sheppard
                        _type: User
                        avatar: https://example.org/users/1/avatar
                        createdAt: '2014-05-21T08:51:20.396Z'
                        email: shep@mail.com
                        firstName: John
                        id: 1
                        lastName: Sheppard
                        login: j.sheppard
                        status: active
                        updatedAt: '2014-05-21T08:51:20.396Z'
                      - _links:
                          delete:
                            href: "/api/v3/users/2"
                            method: DELETE
                            title: Delete j.sheppard2
                          lock:
                            href: "/api/v3/users/2/lock"
                            method: POST
                            title: Set lock on j.sheppard2
                          self:
                            href: "/api/v3/users/2"
                            title: Jim Sheppard - j.sheppard2
                        _type: User
                        avatar: https://example.org/users/1/avatar
                        createdAt: '2014-05-21T08:51:20.396Z'
                        email: shep@mail.net
                        firstName: Jim
                        id: 2
                        lastName: Sheppard
                        login: j.sheppard2
                        status: active
                        updatedAt: '2014-05-21T08:51:20.396Z'
                    _links:
                      self:
                        href: "/api/v3/projects/42/available_assignees"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/Available_AssigneesModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to see the assignable users for this
                      project.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** add work packages

            *Note that you will only receive this error, if you are at least allowed to see the corresponding project.*
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified project does not exist.
          description: |-
            Returned if the project does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view project
          headers: {}
      tags:
      - Work Packages
      description: |-
        Gets a list of users that can be assigned to work packages in the given project.
        This endpoint is deprecated and replaced by [`/api/v3/workspaces/{id}/available_assignees`](https://www.openproject.org/docs/api/endpoints/work-packages/#workspace-available-assignees)
      operationId: Project_Available_assignees
      summary: Project Available assignees
  "/api/v3/projects/{id}/categories":
    get:
      parameters:
      - description: ID of the project whose categories will be listed
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          defaultAssignee:
                            href: "/api/v3/users/42"
                            title: John Sheppard
                          project:
                            href: "/api/v3/projects/11"
                            title: Example project
                          self:
                            href: "/api/v3/categories/10"
                            title: Category with assignee
                        _type: Category
                        id: 10
                        name: Foo
                      - _links:
                          project:
                            href: "/api/v3/projects/11"
                          self:
                            href: "/api/v3/categories/11"
                        _type: Category
                        id: 11
                        name: Bar
                    _links:
                      self:
                        href: "/api/v3/projects/11/categories"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/Categories_by_WorkspaceModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified project does not exist.
          description: |-
            Returned if the project does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view project

            *Note: A client without sufficient permissions shall not be able to test for the existence of a project.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
      tags:
      - Categories
      description: "List all categories of a project\nThis endpoint is deprecated
        and replaced by [`/api/v3/workspaces/{id}/categories`](https://www.openproject.org/docs/api/endpoints/categories/#list-categories-of-a-workspace) "
      operationId: List_categories_of_a_project
      summary: List categories of a project
  "/api/v3/projects/{id}/sprints":
    get:
      parameters:
      - description: ID of the project whose sprints will be listed
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: |-
          JSON specifying filter conditions.

          Accepts the same format and filters as returned by the [sprints](https://www.openproject.org/docs/api/endpoints/sprints/) endpoint.
        example: '[{ "definingWorkspace": { "operator": "=", "values": ["1"] } }]'
        in: query
        name: filters
        required: false
        schema:
          type: string
      - description: Page number inside the requested collection.
        example: 25
        in: query
        name: offset
        required: false
        schema:
          default: 1
          type: integer
      - description: Number of elements to display per page.
        example: 25
        in: query
        name: pageSize
        required: false
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/SprintCollectionModel"
              examples:
                response:
                  "$ref": "#/components/examples/SprintCollectionResponse"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if the user lacks permission to list sprints in the queried for project.

            **Required permission:** view sprints in the project.
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified project does not exist.
          description: |-
            Returned if the project does not exist.

            **Required permission:** view sprints in the queried for project.
          headers: {}
      tags:
      - Sprints
      description: List sprints in the project. The sprints might be ones native to
        the project or shared with it. This endpoint supports pagination and filtering.
      operationId: List_sprints_in_project
      summary: List sprints in project
  "/api/v3/projects/{id}/types":
    get:
      parameters:
      - description: ID of the project whose types will be listed
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          self:
                            href: "/api/v3/types/1"
                        _type: Type
                        color: "#ff0000"
                        createdAt: '2014-05-21T08:51:20.396Z'
                        id: 1
                        isDefault: true
                        isMilestone: false
                        name: Bug
                        position: 1
                        updatedAt: '2014-05-21T08:51:20.396Z'
                      - _links:
                          self:
                            href: "/api/v3/types/2"
                        _type: Type
                        color: "#888"
                        createdAt: '2014-05-21T08:51:20.396Z'
                        id: 2
                        isDefault: false
                        isMilestone: false
                        name: Feature
                        position: 2
                        updatedAt: '2014-05-21T08:51:20.396Z'
                    _links:
                      self:
                        href: "/api/v3/projects/11/types"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/Types_by_WorkspaceModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified project does not exist.
          description: |-
            Returned if the project does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view work packages **or** manage types (on given project)

            *Note: A client without sufficient permissions shall not be able to test for the existence of a project.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
      tags:
      - Types
      description: |-
        This endpoint lists the types that are *available* in a given project.
        This endpoint is deprecated and replaced by [`/api/v3/workspaces/{id}/types`](https://www.openproject.org/docs/api/endpoints/types/#list-types-available-in-a-workspace)
      operationId: List_types_available_in_a_project
      summary: List types available in a project
  "/api/v3/projects/{id}/versions":
    get:
      parameters:
      - description: ID of the project whose versions will be listed
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          availableInProjects:
                            href: "/api/v3/versions/11/workspaces"
                          definingProject:
                            href: "/api/v3/projects/11"
                          self:
                            href: "/api/v3/versions/11"
                        _type: Version
                        description:
                          format: plain
                          html: This version has a description
                          raw: This version has a description
                        endDate:
                        id: 11
                        name: v3.0 Alpha
                        startDate: '2014-11-20'
                        status: Open
                      - _links:
                          availableInProjects:
                            href: "/api/v3/versions/12/workspaces"
                          definingProject:
                            href: "/api/v3/projects/11"
                          self:
                            href: "/api/v3/versions/12"
                        _type: Version
                        description:
                          format: plain
                          html: ''
                          raw: ''
                        endDate:
                        id: 12
                        name: v2.0
                        startDate:
                        status: Closed
                      - _links:
                          availableInProjects:
                            href: "/api/v3/versions/10/workspaces"
                          definingProject:
                            href: "/api/v3/projects/11"
                          self:
                            href: "/api/v3/versions/10"
                        _type: Version
                        description:
                          format: plain
                          html: ''
                          raw: ''
                        endDate:
                        id: 10
                        name: v1.0
                        startDate:
                        status: Open
                    _links:
                      self:
                        href: "/api/v3/projects/11/versions"
                    _type: Collection
                    count: 3
                    total: 3
              schema:
                "$ref": "#/components/schemas/Versions_by_WorkspaceModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified project does not exist.
          description: |-
            Returned if the project does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view work packages **or** manage versions (on given project)

            *Note: A client without sufficient permissions shall not be able to test for the existence of a project.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
      tags:
      - Versions
      description: |-
        This endpoint lists the versions that are *available* in a given project.
        Note that due to sharing this might be more than the versions *defined* by that project.

        This endpoint is deprecated and replaced by [`/api/v3/workspaces/{id}/versions`](https://www.openproject.org/docs/api/endpoints/versions/#list-versions-available-in-a-workspace)
      operationId: List_versions_available_in_a_project
      summary: List versions available in a project
  "/api/v3/projects/{id}/favorite":
    delete:
      parameters:
      - description: Project id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Returned if the project was successfully removed from favorites.
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the project does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view project
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** logged in
      tags:
      - Projects
      - Favorites
      description: |-
        Removes the project from the current user's favorites.

        This endpoint is deprecated and replaced by [`/api/v3/workspaces/{id}/favorite`](https://www.openproject.org/docs/api/endpoints/workspaces/#unfavorite-workspace)
      operationId: Unfavorite_Project
      summary: Unfavorite Project
    post:
      parameters:
      - description: Project id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Returned if the project was successfully added to favorites.
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the project does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view project
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** logged in
      tags:
      - Projects
      - Favorites
      description: |-
        Adds the project to the current user's favorites.

        This endpoint is deprecated and replaced by [`/api/v3/workspaces/{id}/favorite`](https://www.openproject.org/docs/api/endpoints/workspaces/#favorite-workspace)
      operationId: Favorite_Project
      summary: Favorite Project
  "/api/v3/projects/{id}/configuration":
    get:
      parameters:
      - description: Project id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _type: Configuration
                    _links:
                      self:
                        href: "/api/v3/projects/1/configuration"
                      userPreferences:
                        href: "/api/v3/my_preferences"
                    maximumAttachmentFileSize: 5242880
                    perPageOptions:
                    - 20
                    - 100
                    enabledInternalComments: true
              schema:
                "$ref": "#/components/schemas/ProjectConfigurationModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: Returned if the project does not exist or the user cannot view
            it.
          headers: {}
      tags:
      - Configuration
      - Projects
      description: |-
        Returns the configuration scoped to a specific project, including all global
        configuration properties plus project-specific settings.
      operationId: View_project_configuration
      summary: View project configuration
  "/api/v3/queries":
    get:
      summary: List queries
      operationId: List_queries
      tags:
      - Queries
      description: Returns a collection of queries. The collection can be filtered
        via query parameters similar to how work packages are filtered. Please note
        however, that the filters are applied to the queries and not to the work packages
        the queries in turn might return.
      parameters:
      - description: |-
          JSON specifying filter conditions.
          Currently supported filters are:

          + project: filters queries by the project they are assigned to. If the project filter is passed with the `!*` (not any) operator, global queries are returned.

          + id: filters queries based on their id

          + updated_at: filters queries based on the last time they where updated
        example: '[{ "project_id": { "operator": "!*", "values": null } }]'
        in: query
        name: filters
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                Queries:
                  "$ref": "#/components/examples/QueriesModel"
              schema:
                "$ref": "#/components/schemas/QueriesModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to see the queries.
          description: |-
            Returned if the client does not have sufficient permissions to see queries.

            **Required permission:** view work packages or manage public queries in any project
          headers: {}
    post:
      summary: Create query
      operationId: Create_query
      tags:
      - Queries
      description: |-
        When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body.
        The required fields of a Query can be found in its schema, which is embedded in the respective form.
        Note that it is only allowed to provide properties or links supporting the write operation.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Query_Create_Form"
      responses:
        '201':
          content:
            application/hal+json:
              examples:
                Query:
                  "$ref": "#/components/examples/QueryModel"
              schema:
                "$ref": "#/components/schemas/QueryModel"
          description: Created
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _embedded:
                      details:
                        attribute: project
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Project not found
          description: |-
            Returned if:

            * the client tries to modify a read-only property (`PropertyIsReadOnly`)

            * a constraint for a property was violated (`PropertyConstraintViolation`)

            * the client provides a link to an invalid resource (`ResourceTypeMismatch`),
              e.g. a user, project or operator not found
          headers: {}
  "/api/v3/queries/available_projects":
    get:
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          categories:
                            href: "/api/v3/projects/6/categories"
                          createWorkPackage:
                            href: "/api/v3/projects/6/work_packages/form"
                            method: post
                          createWorkPackageImmediate:
                            href: "/api/v3/projects/6/work_packages"
                            method: post
                          self:
                            href: "/api/v3/projects/6"
                            title: A project
                          versions:
                            href: "/api/v3/projects/6/versions"
                        _type: Project
                        createdAt: '2015-07-06T13:28:14+00:00'
                        description: Eveniet molestias omnis quis aut qui eum adipisci.
                        id: 6
                        identifier: a_project
                        name: A project
                        type: Customer Project
                        updatedAt: '2015-10-01T09:55:02+00:00'
                      - _links:
                          categories:
                            href: "/api/v3/projects/14/categories"
                          createWorkPackage:
                            href: "/api/v3/projects/14/work_packages/form"
                            method: post
                          createWorkPackageImmediate:
                            href: "/api/v3/projects/14/work_packages"
                            method: post
                          self:
                            href: "/api/v3/projects/14"
                            title: Another project
                          versions:
                            href: "/api/v3/projects/14/versions"
                        _type: Project
                        createdAt: '2016-02-29T12:50:20+00:00'
                        description: ''
                        id: 14
                        identifier: another_project
                        name: Another project
                        type:
                        updatedAt: '2016-02-29T12:50:20+00:00'
                    _links:
                      self:
                        href: "/api/v3/queries/available_projects"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/Available_projects_for_queryModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** view work packages
          headers: {}
      tags:
      - Queries
      description: Gets a list of projects that are available as projects a query
        can be assigned to.
      operationId: Available_projects_for_query
      summary: Available projects for query
  "/api/v3/queries/columns/{id}":
    get:
      parameters:
      - description: QueryColumn id
        example: priority
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _links:
                      self:
                        href: "/api/v3/queries/columns/priority"
                        title: Priority
                    _type: QueryColumn::Property
                    id: priority
                    name: Priority
              schema:
                "$ref": "#/components/schemas/Query_ColumnModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions to see it.

            **Required permission:** view work package in any project
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified query does not exist.
          description: Returned if the QueryColumn does not exist.
          headers: {}
      tags:
      - Query Columns
      description: Retrieve an individual QueryColumn as identified by the `id` parameter.
      operationId: View_Query_Column
      summary: View Query Column
  "/api/v3/queries/default":
    get:
      summary: View default query
      operationId: View_default_query
      tags:
      - Queries
      description: Same as [viewing an existing, persisted Query](https://www.openproject.org/docs/api/endpoints/queries/#list-queries)
        in its response, this resource returns an unpersisted query and by that allows
        to get the default query configuration. The client may also provide additional
        parameters which will modify the default query.
      parameters:
      - name: filters
        description: |-
          JSON specifying filter conditions.
          The filters provided as parameters are not applied to the query but are instead used to override the query's persisted filters.
          All filters also accepted by the work packages endpoint are accepted. If no filter is to be applied, the client should send an empty array (`[]`).
        example: '[{ "assignee": { "operator": "=", "values": ["1", "5"] } }]'
        in: query
        required: false
        schema:
          default: '[{ "status_id": { "operator": "o", "values": null }}]'
          type: string
      - name: offset
        description: Page number inside the queries' result collection of work packages.
        example: 25
        in: query
        required: false
        schema:
          default: 1
          type: integer
      - name: pageSize
        description: Number of elements to display per page for the queries' result
          collection of work packages.
        example: 25
        in: query
        required: false
        schema:
          type: integer
      - name: sortBy
        description: JSON specifying sort criteria. The sort criteria is applied to
          the query's result collection of work packages overriding the query's persisted
          sort criteria.
        example: '[["status", "asc"]]'
        in: query
        required: false
        schema:
          default: '[["id", "asc"]]'
          type: string
      - name: groupBy
        description: The column to group by. The grouping criteria is applied to the
          to the query's result collection of work packages overriding the query's
          persisted group criteria.
        example: status
        in: query
        required: false
        schema:
          type: string
      - name: showSums
        description: Indicates whether properties should be summed up if they support
          it. The showSums parameter is applied to the to the query's result collection
          of work packages overriding the query's persisted sums property.
        example: true
        in: query
        required: false
        schema:
          default: false
          type: boolean
      - name: timestamps
        description: 'Indicates the timestamps to filter by when showing changed attributes
          on work packages. Values can be either ISO8601 dates, ISO8601 durations
          and the following relative date keywords: "oneDayAgo@HH:MM+HH:MM", "lastWorkingDay@HH:MM+HH:MM",
          "oneWeekAgo@HH:MM+HH:MM", "oneMonthAgo@HH:MM+HH:MM". The first "HH:MM" part
          represents the zero paded hours and minutes. The last "+HH:MM" part represents
          the timezone offset from UTC associated with the time, the offset can be
          positive or negative e.g."oneDayAgo@01:00+01:00", "oneDayAgo@01:00-01:00".
          Values older than 1 day are accepted only with valid Enterprise Token available.

          '
        example: 2023-01-01,P-1Y,PT0S,lastWorkingDay@12:00
        in: query
        required: false
        schema:
          default: PT0S
          type: string
      - name: timelineVisible
        description: Indicates whether the timeline should be shown.
        example: true
        in: query
        required: false
        schema:
          default: false
          type: boolean
      - name: timelineZoomLevel
        description: Indicates in what zoom level the timeline should be shown. Valid
          values are  `days`, `weeks`, `months`, `quarters`, and `years`.
        example: days
        in: query
        required: false
        schema:
          default: days
          type: string
      - name: showHierarchies
        description: Indicates whether the hierarchy mode should be enabled.
        example: true
        in: query
        required: false
        schema:
          default: true
          type: boolean
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      results:
                        _embedded:
                          elements:
                          - "<--- shortened for brevity --->"
                        _links:
                          changeSize:
                            href: "/api/v3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=%7Bsize%7D&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                            templated: true
                          createWorkPackage:
                            href: "/api/v3/work_packages/form"
                            method: post
                          createWorkPackageImmediate:
                            href: "/api/v3/work_packages"
                            method: post
                          jumpTo:
                            href: "/api/v3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=%7Boffset%7D&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                            templated: true
                          self:
                            href: "/api/v3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                        _type: WorkPackageCollection
                        count: 30
                        offset: 1
                        pageSize: 2
                        total: 234
                    _links:
                      columns:
                      - href: "/api/v3/queries/columns/id"
                        title: ID
                      - href: "/api/v3/queries/columns/subject"
                        title: Subject
                      - href: "/api/v3/queries/columns/type"
                        title: Type
                      - href: "/api/v3/queries/columns/status"
                        title: Status
                      - href: "/api/v3/queries/columns/priority"
                        title: Priority
                      - href: "/api/v3/queries/columns/assignee"
                        title: Assignee
                      - href: "/api/v3/queries/columns/updated_at"
                        title: Updated on
                      groupBy:
                        href:
                        title:
                      highlightedAttributes: []
                      project:
                        href:
                      results:
                        href: "/api/v3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                      self:
                        href: "/api/v3/queries/default"
                        title: Default
                      sortBy:
                      - href: "/api/v3/queries/sort_bys/parent-desc"
                        title: Parent (Descending)
                      user:
                        href: "/api/v3/users/1"
                        title: OpenProject Admin
                    _type: Query
                    filters:
                    - _links:
                        filter:
                          href: "/api/v3/queries/filters/status"
                          title: Status
                        operator:
                          href: "/api/v3/queries/operators/o"
                          title: open
                        schema:
                          href: "/api/v3/queries/filter_instance_schemas/status"
                        values: []
                      _type: StatusQueryFilter
                      name: Status
                    highlightingMode: inline
                    name: default
                    public: false
                    showHierarchies: true
                    starred: false
                    sums: false
                    timelineLabels: {}
                    timelineVisible: false
                    timelineZoomLevel: days
              schema:
                "$ref": "#/components/schemas/Default_QueryModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions to see the default query.

            **Required permission:** view work packages in any project
          headers: {}
  "/api/v3/queries/filter_instance_schemas":
    get:
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _dependencies:
                        - _type: SchemaDependency
                          dependencies:
                            "/api/v3/queries/operators/!":
                              values:
                                _links: {}
                                hasDefault: false
                                name: Values
                                required: true
                                type: "[]User"
                                writable: true
                            "/api/v3/queries/operators/!*": {}
                            "/api/v3/queries/operators/*": {}
                            "/api/v3/queries/operators/=":
                              values:
                                _links: {}
                                hasDefault: false
                                name: Values
                                required: true
                                type: "[]User"
                                writable: true
                          'on': operator
                        _links:
                          filter:
                            href: "/api/v3/queries/filters/assignee"
                            title: Assignee
                          self:
                            href: "/api/v3/queries/filter_instance_schemas/assignee"
                        _type: QueryFilterInstanceSchema
                        filter:
                          _links: {}
                          hasDefault: false
                          name: Filter
                          required: true
                          type: QueryFilter
                          writable: true
                        name:
                          hasDefault: true
                          name: Name
                          required: true
                          type: String
                          writable: false
                      - _dependencies:
                        - _type: SchemaDependency
                          dependencies:
                            "/api/v3/queries/operators/!":
                              values:
                                _links: {}
                                hasDefault: false
                                name: Values
                                required: true
                                type: "[]User"
                                writable: true
                            "/api/v3/queries/operators/=":
                              values:
                                _links: {}
                                hasDefault: false
                                name: Values
                                required: true
                                type: "[]User"
                                writable: true
                          'on': operator
                        _links:
                          filter:
                            href: "/api/v3/queries/filters/author"
                            title: Author
                          self:
                            href: "/api/v3/queries/filter_instance_schemas/author"
                        _type: QueryFilterInstanceSchema
                        filter:
                          _links: {}
                          hasDefault: false
                          name: Filter
                          required: true
                          type: QueryFilter
                          writable: true
                        name:
                          hasDefault: true
                          name: Name
                          required: true
                          type: String
                          writable: false
                    _links:
                      self:
                        href: "/api/v3/queries/filter_instance_schemas"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/Query_Filter_Instance_SchemasModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions to see it.

            **Required permission:** view work package in any project
          headers: {}
      tags:
      - Query Filter Instance Schema
      description: Returns the list of QueryFilterInstanceSchemas defined for a global
        query. That is a query not assigned to a project.
      operationId: List_Query_Filter_Instance_Schemas
      summary: List Query Filter Instance Schemas
  "/api/v3/queries/filter_instance_schemas/{id}":
    get:
      parameters:
      - description: QueryFilterInstanceSchema identifier. The identifier is the filter
          identifier.
        example: author
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _dependencies:
                    - _type: SchemaDependency
                      dependencies:
                        "/api/v3/queries/operators/!":
                          values:
                            _links: {}
                            hasDefault: false
                            name: Values
                            required: true
                            type: "[]User"
                            writable: true
                        "/api/v3/queries/operators/=":
                          values:
                            _links: {}
                            hasDefault: false
                            name: Values
                            required: true
                            type: "[]User"
                            writable: true
                      'on': operator
                    _links:
                      filter:
                        href: "/api/v3/queries/filters/author"
                        title: Author
                      self:
                        href: "/api/v3/queries/filter_instance_schemas/author"
                    _type: QueryFilterInstanceSchema
                    filter:
                      _links: {}
                      hasDefault: false
                      name: Filter
                      required: true
                      type: QueryFilter
                      writable: true
                    name:
                      hasDefault: true
                      name: Name
                      required: true
                      type: String
                      writable: false
              schema:
                "$ref": "#/components/schemas/Query_Filter_Instance_SchemaModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions to see it.

            **Required permission:** view work package in any project
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified query does not exist.
          description: Returned if the QueryFilterInstanceSchema does not exist.
          headers: {}
      tags:
      - Query Filter Instance Schema
      description: Retrieve an individual QueryFilterInstanceSchema as identified
        by the id parameter.
      operationId: View_Query_Filter_Instance_Schema
      summary: View Query Filter Instance Schema
  "/api/v3/queries/filters/{id}":
    get:
      parameters:
      - description: QueryFilter identifier
        example: status
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _links:
                      self:
                        href: "/api/v3/queries/filters/status"
                        title: Status
                    _type: QueryFilter
                    id: status
              schema:
                "$ref": "#/components/schemas/Query_FilterModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions to see it.

            **Required permission:** view work package in any project
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified query does not exist.
          description: Returned if the QueryFilter does not exist.
          headers: {}
      tags:
      - Query Filters
      description: Retrieve an individual QueryFilter as identified by the id parameter.
      operationId: View_Query_Filter
      summary: View Query Filter
  "/api/v3/queries/form":
    post:
      summary: Query Create Form
      operationId: Query_Create_Form
      tags:
      - Queries
      description: ''
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Query_Create_Form"
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/QueryFormModel"
          description: OK
          headers: {}
  "/api/v3/queries/operators/{id}":
    get:
      parameters:
      - description: QueryOperator id
        example: "!"
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _links:
                      self:
                        href: "/api/v3/queries/operators/!"
                        title: is not
                    _type: QueryOperator
                    id: "!"
                    name: is not
              schema:
                "$ref": "#/components/schemas/Query_OperatorModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions to see it.

            **Required permission:** view work package in any project
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified query does not exist.
          description: Returned if the QueryOperator does not exist.
          headers: {}
      tags:
      - Query Operators
      description: Retrieve an individual QueryOperator as identified by the `id`
        parameter.
      operationId: View_Query_Operator
      summary: View Query Operator
  "/api/v3/queries/schema":
    get:
      summary: View schema for global queries
      operationId: View_schema_for_global_queries
      tags:
      - Queries
      description: Retrieve the schema for global queries, those, that are not assigned
        to a project.
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                QuerySchema:
                  "$ref": "#/components/examples/QuerySchemaModel"
              schema:
                "$ref": "#/components/schemas/Schema_For_Global_QueriesModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: "**Required permission:** view work package in any project"
          headers: {}
  "/api/v3/queries/sort_bys/{id}":
    get:
      parameters:
      - description: QuerySortBy identifier. The identifier is a combination of the
          column identifier and the direction.
        example: status-asc
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _links:
                      column:
                        href: "/api/v3/queries/columns/status"
                        title: Status
                      direction:
                        href: urn:openproject-org:api:v3:queries:directions:asc
                        title: Ascending
                      self:
                        href: "/api/v3/queries/sort_bys/status-asc"
                        title: Status (Ascending)
                    _type: QuerySortBy
                    id: status-asc
                    name: Status (Ascending)
              schema:
                "$ref": "#/components/schemas/Query_Sort_ByModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions to see it.

            **Required permission:** view work package in any project
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified query does not exist.
          description: Returned if the QuerySortBy does not exist.
          headers: {}
      tags:
      - Query Sort Bys
      description: Retrieve an individual QuerySortBy as identified by the id parameter.
      operationId: View_Query_Sort_By
      summary: View Query Sort By
  "/api/v3/queries/{id}":
    delete:
      summary: Delete query
      operationId: Delete_query
      tags:
      - Queries
      description: Delete the query identified by the id parameter
      parameters:
      - description: Query id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: No Content
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** for own queries none; for public queries: manage public queries

            *Note that you will only receive this error, if you are at least allowed to see the corresponding query.*
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the query does not exist or the client does not have sufficient permissions to see it.

            **Required condition:** query belongs to user or query is public

            **Required permission:** view work package in queries project
          headers: {}
    get:
      summary: View query
      operationId: View_query
      tags:
      - Queries
      description: Retrieve an individual query as identified by the id parameter.
        Then endpoint accepts a number of parameters that can be used to override
        the resources' persisted parameters.
      parameters:
      - name: id
        description: Query id
        example: 1
        in: path
        required: true
        schema:
          type: integer
      - name: filters
        description: |-
          JSON specifying filter conditions.
          The filters provided as parameters are not applied to the query but are instead used to override the query's persisted filters.
          All filters also accepted by the work packages endpoint are accepted. If no filter is to be applied, the client should send an empty array (`[]`).
        example: '[{ "assignee": { "operator": "=", "values": ["1", "5"] } }]'
        in: query
        required: false
        schema:
          default: '[{ "status_id": { "operator": "o", "values": null }}]'
          type: string
      - name: offset
        description: Page number inside the queries' result collection of work packages.
        example: 25
        in: query
        required: false
        schema:
          default: 1
          type: integer
      - name: pageSize
        description: Number of elements to display per page for the queries' result
          collection of work packages.
        example: 25
        in: query
        required: false
        schema:
          type: integer
      - name: columns
        description: |-
          Selected columns for the table view. Repeat the parameter for every column,
          e.g. `columns[]=type&columns[]=priority`.
        example:
        - type
        - priority
        in: query
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: sortBy
        description: JSON specifying sort criteria. The sort criteria is applied to
          the query's result collection of work packages overriding the query's persisted
          sort criteria.
        example: '[["status", "asc"]]'
        in: query
        required: false
        schema:
          default: '[["id", "asc"]]'
          type: string
      - name: groupBy
        description: The column to group by. The grouping criteria is applied to the
          to the query's result collection of work packages overriding the query's
          persisted group criteria.
        example: status
        in: query
        required: false
        schema:
          type: string
      - name: showSums
        description: Indicates whether properties should be summed up if they support
          it. The showSums parameter is applied to the to the query's result collection
          of work packages overriding the query's persisted sums property.
        example: true
        in: query
        required: false
        schema:
          default: false
          type: boolean
      - name: timestamps
        description: 'Indicates the timestamps to filter by when showing changed attributes
          on work packages. Values can be either ISO8601 dates, ISO8601 durations
          and the following relative date keywords: "oneDayAgo@HH:MM+HH:MM", "lastWorkingDay@HH:MM+HH:MM",
          "oneWeekAgo@HH:MM+HH:MM", "oneMonthAgo@HH:MM+HH:MM". The first "HH:MM" part
          represents the zero paded hours and minutes. The last "+HH:MM" part represents
          the timezone offset from UTC associated with the time, the offset can be
          positive or negative e.g."oneDayAgo@01:00+01:00", "oneDayAgo@01:00-01:00".
          Values older than 1 day are accepted only with valid Enterprise Token available.

          '
        example: 2023-01-01,P-1Y,PT0S,lastWorkingDay@12:00
        in: query
        required: false
        schema:
          default: PT0S
          type: string
      - name: timelineVisible
        description: Indicates whether the timeline should be shown.
        example: true
        in: query
        required: false
        schema:
          default: false
          type: boolean
      - name: timelineLabels
        description: Overridden labels in the timeline view
        example: "{}"
        in: query
        required: false
        schema:
          default: "{}"
          type: string
      - name: highlightingMode
        description: Highlighting mode for the table view.
        example: inline
        in: query
        required: false
        schema:
          default: inline
          type: string
      - name: highlightedAttributes
        description: |-
          Highlighted attributes mode for the table view when `highlightingMode` is `inline`.
          Repeat the parameter for every attribute, e.g.
          `highlightedAttributes[]=type&highlightedAttributes[]=priority`.
          When omitted, all highlightable attributes will be returned as `highlightedAttributes`.
        example:
        - type
        - priority
        in: query
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: showHierarchies
        description: Indicates whether the hierarchy mode should be enabled.
        example: true
        in: query
        required: false
        schema:
          default: true
          type: boolean
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                Query:
                  "$ref": "#/components/examples/QueryModel"
              schema:
                "$ref": "#/components/schemas/QueryModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified query does not exist.
          description: |-
            Returned if the query does not exist or the client does not have sufficient permissions to see it.

            **Required condition:** query belongs to user or query is public

            **Required permission:** view work package in queries project
          headers: {}
    patch:
      summary: Edit Query
      operationId: Edit_Query
      tags:
      - Queries
      description: |-
        When calling this endpoint the client provides a single object, containing the properties and links that it wants to change, in the body.
        Note that it is only allowed to provide properties or links supporting the **write** operation.
      parameters:
      - description: Query id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Query_Update_Form"
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      highlightedAttributes: []
                      results:
                        _embedded:
                          elements:
                          - "<--- shortened for brevity --->"
                        _links:
                          changeSize:
                            href: "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=%7Bsize%7D&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                            templated: true
                          createWorkPackage:
                            href: "/api/v3/work_packages/form"
                            method: post
                          createWorkPackageImmediate:
                            href: "/api/v3/work_packages"
                            method: post
                          jumpTo:
                            href: "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=%7Boffset%7D&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                            templated: true
                          self:
                            href: "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                        _type: WorkPackageCollection
                        count: 30
                        offset: 1
                        pageSize: 2
                        total: 234
                    _links:
                      columns:
                      - href: "/api/v3/queries/columns/id"
                        title: ID
                      - href: "/api/v3/queries/columns/subject"
                        title: Subject
                      - href: "/api/v3/queries/columns/type"
                        title: Type
                      - href: "/api/v3/queries/columns/status"
                        title: Status
                      - href: "/api/v3/queries/columns/priority"
                        title: Priority
                      - href: "/api/v3/queries/columns/assignee"
                        title: Assignee
                      - href: "/api/v3/queries/columns/updated_at"
                        title: Updated on
                      groupBy:
                        href:
                        title:
                      highlightedAttributes: []
                      project:
                        href: "/api/v3/projects/3"
                        title: copy
                      results:
                        href: "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                      self:
                        href: "/api/v3/queries/9"
                        title: fdsfdsfdsf
                      sortBy:
                      - href: "/api/v3/queries/sort_bys/parent-desc"
                        title: Parent (Descending)
                      user:
                        href: "/api/v3/users/1"
                        title: OpenProject Admin
                    _type: Query
                    createdAt: '2015-03-20T12:56:56.343Z'
                    filters:
                    - _links:
                        filter:
                          href: "/api/v3/queries/filters/status"
                          title: Status
                        operator:
                          href: "/api/v3/queries/operators/o"
                          title: open
                        schema:
                          href: "/api/v3/queries/filter_instance_schemas/status"
                        values: []
                      _type: StatusQueryFilter
                      name: Status
                    - _links:
                        filter:
                          href: "/api/v3/queries/filters/dueDate"
                          title: Finish date
                        operator:
                          href: "/api/v3/queries/operators/<t+"
                          title: in less than
                        schema:
                          href: "/api/v3/queries/filter_instance_schemas/dueDate"
                      _type: DueDateQueryFilter
                      name: Finish date
                      values:
                      - '1'
                    id: 9
                    name: fdsfdsfdsf
                    public: false
                    starred: false
                    sums: false
                    updatedAt: '2015-05-20T18:16:53.884Z'
              schema:
                "$ref": "#/components/schemas/QueryModel"
          description: OK
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to edit the content of the work package.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit work package
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified query does not exist.
          description: |-
            Returned if the query does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work packages in the query's project (unless global)
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _embedded:
                      details:
                        attribute: name
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: The name might not be blank.
          description: |-
            Returned if:

            * the client tries to modify a read-only property (`PropertyIsReadOnly`)

            * a constraint for a property was violated (`PropertyConstraintViolation`)

            * the client provides a link to an invalid resource (`ResourceTypeMismatch`)
          headers: {}
  "/api/v3/queries/{id}/form":
    post:
      summary: Query Update Form
      operationId: Query_Update_Form
      tags:
      - Queries
      description: ''
      parameters:
      - description: Query id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Query_Update_Form"
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/QueryFormModel"
          description: OK
          headers: {}
  "/api/v3/queries/{id}/star":
    patch:
      parameters:
      - description: Query id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      results:
                        _embedded:
                          elements:
                          - "<--- shortened for brevity --->"
                        _links:
                          changeSize:
                            href: "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=%7Bsize%7D&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                            templated: true
                          createWorkPackage:
                            href: "/api/v3/work_packages/form"
                            method: post
                          createWorkPackageImmediate:
                            href: "/api/v3/work_packages"
                            method: post
                          jumpTo:
                            href: "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=%7Boffset%7D&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                            templated: true
                          self:
                            href: "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                        _type: WorkPackageCollection
                        count: 30
                        offset: 1
                        pageSize: 2
                        total: 234
                    _links:
                      columns:
                      - href: "/api/v3/queries/columns/id"
                        title: ID
                      - href: "/api/v3/queries/columns/subject"
                        title: Subject
                      - href: "/api/v3/queries/columns/type"
                        title: Type
                      - href: "/api/v3/queries/columns/status"
                        title: Status
                      - href: "/api/v3/queries/columns/priority"
                        title: Priority
                      - href: "/api/v3/queries/columns/assignee"
                        title: Assignee
                      - href: "/api/v3/queries/columns/updated_at"
                        title: Updated on
                      groupBy:
                        href:
                        title:
                      project:
                        href: "/api/v3/projects/3"
                        title: copy
                      results:
                        href: "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                      self:
                        href: "/api/v3/queries/9"
                        title: fdsfdsfdsf
                      sortBy:
                      - href: "/api/v3/queries/sort_bys/parent-desc"
                        title: Parent (Descending)
                      user:
                        href: "/api/v3/users/1"
                        title: OpenProject Admin
                    _type: Query
                    createdAt: '2015-03-20T12:56:56.856Z'
                    filters:
                    - _links:
                        filter:
                          href: "/api/v3/queries/filters/status"
                          title: Status
                        operator:
                          href: "/api/v3/queries/operators/o"
                          title: open
                        schema:
                          href: "/api/v3/queries/filter_instance_schemas/status"
                        values: []
                      _type: StatusQueryFilter
                      name: Status
                    - _links:
                        filter:
                          href: "/api/v3/queries/filters/dueDate"
                          title: Finish date
                        operator:
                          href: "/api/v3/queries/operators/<t+"
                          title: in less than
                        schema:
                          href: "/api/v3/queries/filter_instance_schemas/dueDate"
                      _type: DueDateQueryFilter
                      name: Finish date
                      values:
                      - '1'
                    id: 9
                    name: fdsfdsfdsf
                    public: false
                    starred: true
                    sums: false
                    updatedAt: '2015-05-20T18:16:53.089Z'
              schema:
                "$ref": "#/components/schemas/Star_QueryModel"
          description: OK
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to star this query.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** for own queries none; for public queries: manage public queries

            *Note that you will only receive this error, if you are at least allowed to see the corresponding query.*
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified query does not exist.
          description: |-
            Returned if the query does not exist or the client does not have sufficient permissions to see it.

            **Required condition:** query belongs to user or query is public

            **Required permission:** view work package in queries project
          headers: {}
      tags:
      - Queries
      description: ''
      operationId: Star_query
      summary: Star query
  "/api/v3/queries/{id}/unstar":
    patch:
      parameters:
      - description: Query id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      results:
                        _embedded:
                          elements:
                          - "<--- shortened for brevity --->"
                        _links:
                          changeSize:
                            href: "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=%7Bsize%7D&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                            templated: true
                          createWorkPackage:
                            href: "/api/v3/work_packages/form"
                            method: post
                          createWorkPackageImmediate:
                            href: "/api/v3/work_packages"
                            method: post
                          jumpTo:
                            href: "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=%7Boffset%7D&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                            templated: true
                          self:
                            href: "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                        _type: WorkPackageCollection
                        count: 30
                        offset: 1
                        pageSize: 2
                        total: 234
                    _links:
                      columns:
                      - href: "/api/v3/queries/columns/id"
                        title: ID
                      - href: "/api/v3/queries/columns/subject"
                        title: Subject
                      - href: "/api/v3/queries/columns/type"
                        title: Type
                      - href: "/api/v3/queries/columns/status"
                        title: Status
                      - href: "/api/v3/queries/columns/priority"
                        title: Priority
                      - href: "/api/v3/queries/columns/assignee"
                        title: Assignee
                      - href: "/api/v3/queries/columns/updated_at"
                        title: Updated on
                      groupBy:
                        href:
                        title:
                      project:
                        href: "/api/v3/projects/3"
                        title: copy
                      results:
                        href: "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                      self:
                        href: "/api/v3/queries/9"
                        title: fdsfdsfdsf
                      sortBy:
                      - href: "/api/v3/queries/sort_bys/parent-desc"
                        title: Parent (Descending)
                      user:
                        href: "/api/v3/users/1"
                        title: OpenProject Admin
                    _type: Query
                    createdAt: '2015-03-20T12:56:56.468Z'
                    filters:
                    - _links:
                        filter:
                          href: "/api/v3/queries/filters/status"
                          title: Status
                        operator:
                          href: "/api/v3/queries/operators/o"
                          title: open
                        schema:
                          href: "/api/v3/queries/filter_instance_schemas/status"
                        values: []
                      _type: StatusQueryFilter
                      name: Status
                    - _links:
                        filter:
                          href: "/api/v3/queries/filters/dueDate"
                          title: Finish date
                        operator:
                          href: "/api/v3/queries/operators/<t+"
                          title: in less than
                        schema:
                          href: "/api/v3/queries/filter_instance_schemas/dueDate"
                      _type: DueDateQueryFilter
                      name: Finish date
                      values:
                      - '1'
                    id: 9
                    name: fdsfdsfdsf
                    public: false
                    starred: false
                    sums: false
                    updatedAt: '2015-05-20T18:16:53.386Z'
              schema:
                "$ref": "#/components/schemas/Unstar_QueryModel"
          description: OK
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to unstar this query.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** for own queries none; for public queries: manage public queries

            *Note that you will only receive this error, if you are at least allowed to see the corresponding query.*
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified query does not exist.
          description: |-
            Returned if the query does not exist or the client does not have sufficient permissions to see it.

            **Required condition:** query belongs to user or query is public

            **Required permission:** view work package in queries project
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
      tags:
      - Queries
      description: ''
      operationId: Unstar_query
      summary: Unstar query
  "/api/v3/recurring_meetings":
    get:
      summary: List all visible recurring meetings
      operationId: list_recurring_meetings
      tags:
      - Recurring Meetings
      description: Retrieve a paginated collection of recurring meetings visible to
        the authenticated user.
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/RecurringMeetingCollectionModel"
    post:
      summary: Create recurring meeting
      operationId: create_recurring_meeting
      tags:
      - Recurring Meetings
      description: |-
        Creates a new recurring meeting series applying the attributes provided in the body.
        A template meeting is automatically created alongside the recurring meeting.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/RecurringMeetingWriteModel"
      responses:
        '201':
          description: Created
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/RecurringMeetingModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** create meetings in the given project
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
  "/api/v3/recurring_meetings/{id}":
    get:
      summary: Get a recurring meeting
      operationId: get_recurring_meeting
      tags:
      - Recurring Meetings
      description: Retrieve an individual recurring meeting series as identified by
        the id parameter.
      parameters:
      - description: Recurring meeting identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/RecurringMeetingModel"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the recurring meeting does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view meetings in the recurring meeting's project
    patch:
      summary: Update recurring meeting
      operationId: update_recurring_meeting
      tags:
      - Recurring Meetings
      description: |-
        Updates the given recurring meeting series by applying the attributes provided in the body.
        If schedule-related attributes (frequency, interval, startTime, endAfter, etc.) are changed,
        the meeting schedule is automatically recalculated.
      parameters:
      - description: Recurring meeting identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/RecurringMeetingWriteModel"
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/RecurringMeetingModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit meetings in the recurring meeting's project
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the recurring meeting does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view meetings in the recurring meeting's project
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
    delete:
      summary: Delete recurring meeting
      operationId: delete_recurring_meeting
      tags:
      - Recurring Meetings
      description: |-
        Deletes the entire recurring meeting series, including the template meeting and all
        scheduled occurrences that have not yet been instantiated. Already-created meeting
        instances are not deleted.
      parameters:
      - description: Recurring meeting identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Returned if the recurring meeting was successfully deleted.
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** delete meetings
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the recurring meeting does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view meetings in the recurring meeting's project
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
  "/api/v3/recurring_meetings/{id}/end":
    post:
      summary: End a meeting series
      operationId: end_recurring_meeting
      tags:
      - Recurring Meetings
      description: |-
        Ends the recurring meeting series. The series end date is set so that no further
        occurrences are scheduled, any future already-instantiated occurrences are cancelled
        and removed, and participants receive cancellation and "series ended" notification emails
        if `notify` is set to true for the series.

        Ending a series before its first occurrence is rejected.

        Returns the updated `RecurringMeeting` resource.
      parameters:
      - description: Recurring meeting ID
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Returned if the series was ended successfully.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/RecurringMeetingModel"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit meetings in the recurring meeting's project
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the recurring meeting does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view meetings in the recurring meeting's project
        '422':
          description: Returned if the series could not be ended, for example because
            it has not started yet.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: End date must be after the series start date.
  "/api/v3/recurring_meetings/{id}/template_completed":
    post:
      summary: Complete the series template
      operationId: complete_recurring_meeting_template
      tags:
      - Recurring Meetings
      description: "Completes the series template and starts the recurring meeting.
        This exits draft mode,\ninitiates the first occurrence from it, and schedules
        the job that creates the next\noccurrence.\n\nThe `notify` flag sets the series-wide
        email notification setting (stored on the template).\nWhen `true`, the initial
        series invitations are sent to the template participants. \n`notify` must
        be provided explicitly.\n\nCompleting an already-completed series is rejected.\n\nReturns
        the updated `RecurringMeeting` resource."
      parameters:
      - description: Recurring meeting ID
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - notify
              properties:
                notify:
                  type: boolean
                  description: |-
                    Enable email notifications for the series.
                    When `true`, the initial invitations are sent to the template participants.
            example:
              notify: true
      responses:
        '200':
          description: Returned when the template is completed successfully.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/RecurringMeetingModel"
        '400':
          description: Returned if the required `notify` parameter is missing.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:BadRequest
                    message: 'Bad request: notify is missing'
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit meetings in the recurring meeting's project
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the recurring meeting does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view meetings in the recurring meeting's project
        '422':
          description: |-
            Returned if the template could not be completed, for example because the series has no
            next occurrence to schedule or it has already been completed.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:UnprocessableContent
                    message: The first occurrence of this meeting series is already
                      instantiated.
  "/api/v3/recurring_meetings/{id}/occurrences/upcoming":
    get:
      summary: List upcoming occurrences of a recurring meeting
      operationId: list_recurring_meeting_occurrences_upcoming
      tags:
      - Recurring Meetings
      description: |-
        Returns a collection of upcoming occurrences for the given recurring meeting.
        The list merges computed occurrences from the recurrence schedule (via IceCube) with
        any persisted `ScheduledMeeting` records, including already-instantiated open meetings.

        Occurrences are ordered chronologically and limited by the `limit` parameter.
      parameters:
      - description: Recurring meeting identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: Maximum number of occurrences to return. Defaults to 20.
        example: 20
        in: query
        name: limit
        required: false
        schema:
          type: integer
          default: 20
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/RecurringMeetingOccurrenceCollectionModel"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the recurring meeting does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view meetings in the recurring meeting's project
  "/api/v3/recurring_meetings/{id}/occurrences/past":
    get:
      summary: List past occurrences of a recurring meeting
      operationId: list_recurring_meeting_occurrences_past
      tags:
      - Recurring Meetings
      description: |-
        Returns a collection of past, non-cancelled occurrences for the given recurring meeting.
        Only persisted `ScheduledMeeting` records with a `start_time` in the past are returned.
      parameters:
      - description: Recurring meeting identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/RecurringMeetingOccurrenceCollectionModel"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the recurring meeting does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view meetings in the recurring meeting's project
  "/api/v3/recurring_meetings/{id}/occurrences/cancelled":
    get:
      summary: List cancelled occurrences of a recurring meeting
      operationId: list_recurring_meeting_occurrences_cancelled
      tags:
      - Recurring Meetings
      description: |-
        Returns a collection of cancelled occurrences for the given recurring meeting.
        Only persisted `ScheduledMeeting` records with `cancelled: true` are returned.
      parameters:
      - description: Recurring meeting identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/RecurringMeetingOccurrenceCollectionModel"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the recurring meeting does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view meetings in the recurring meeting's project
  "/api/v3/recurring_meetings/{id}/occurrences/open":
    get:
      summary: List open occurrences of a recurring meeting
      operationId: list_recurring_meeting_occurrences_open
      tags:
      - Recurring Meetings
      description: |-
        Returns a collection of open (instantiated, non-cancelled) occurrences for the given recurring meeting.
        Only persisted `ScheduledMeeting` records that have an associated meeting and are not cancelled are returned.
      parameters:
      - description: Recurring meeting identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/RecurringMeetingOccurrenceCollectionModel"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the recurring meeting does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view meetings in the recurring meeting's project
  "/api/v3/recurring_meetings/{id}/occurrences/{start_time}":
    delete:
      summary: Cancel an occurrence
      operationId: cancel_recurring_meeting_occurrence
      tags:
      - Recurring Meetings
      description: |-
        Cancels the occurrence at the given `start_time` for this recurring meeting series.
        A `ScheduledMeeting` record is created (or updated) with `cancelled: true`.

        An occurrence that has already been instantiated as a meeting cannot be cancelled via this
        endpoint — delete the meeting directly via `DELETE /api/v3/meetings/{id}` instead.
      parameters:
      - description: Recurring meeting identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: The ISO 8601 start time of the occurrence to cancel (e.g. `2025-06-02T10:00:00Z`)
        example: '2025-06-02T10:00:00Z'
        in: path
        name: start_time
        required: true
        schema:
          type: string
          format: date-time
      responses:
        '204':
          description: Returned if the occurrence was successfully cancelled.
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit meetings in the recurring meeting's project
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the recurring meeting does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view meetings in the recurring meeting's project
        '409':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:Conflict
                    message: Cannot cancel an already instantiated occurrence. Delete
                      the meeting instead.
          description: |-
            Returned if the occurrence has already been instantiated as a meeting.
            Delete the meeting directly via `DELETE /api/v3/meetings/{id}` instead.
  "/api/v3/recurring_meetings/{id}/occurrences/{start_time}/init":
    post:
      summary: Instantiate an occurrence
      operationId: init_recurring_meeting_occurrence
      tags:
      - Recurring Meetings
      description: |-
        Instantiates the occurrence at the given `start_time` by creating a real meeting from
        the recurring meeting's template. Returns the newly created `Meeting` resource.

        If a previously cancelled occurrence exists for this `start_time`, it is restored, and
        if `notify` is set to true, its participants are notified via email.
      parameters:
      - description: Recurring meeting identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: The ISO 8601 start time of the occurrence to instantiate (e.g.
          `2025-06-02T10:00:00Z`)
        example: '2025-06-02T10:00:00Z'
        in: path
        name: start_time
        required: true
        schema:
          type: string
          format: date-time
      responses:
        '201':
          description: Created — the occurrence was successfully instantiated as a
            meeting.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/MeetingModel"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** create meetings in the recurring meeting's project
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the recurring meeting does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view meetings in the recurring meeting's project
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
  "/api/v3/relations":
    get:
      summary: List Relations
      operationId: list_relations
      tags:
      - Relations
      description: |-
        Lists all relations according to the given (optional, logically conjunctive) filters and ordered by ID.
        The response only includes relations between work packages which the user is allowed to see.
      parameters:
      - name: filters
        description: |-
          JSON specifying filter conditions. Accepts the same format as returned by
          the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Valid fields to filter by are:

          - id - ID of relation
          - from - ID of work package from which the filtered relations emanates.
          - to - ID of work package to which this related points.
          - involved - ID of either the `from` or the `to` work package.
          - type - The type of relation to filter by, e.g. "follows".
        example: '[{ "from": { "operator": "=", "values": 42 } }]'
        in: query
        required: false
        schema:
          type: string
      - name: sortBy
        description: |-
          JSON specifying sort criteria.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint.
        example: '[["type", "asc"]]'
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/RelationCollectionModel"
              examples:
                response:
                  "$ref": "#/components/examples/RelationCollectionResponse"
        '400':
          description: Returned if the client provides invalid filter parameters.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
                    message:
                    - Filters Type filter has invalid values.
  "/api/v3/relations/{id}":
    get:
      summary: Get Relation
      operationId: get_relation
      tags:
      - Relations
      description: Get a single relation specified by its unique identifier.
      parameters:
      - description: Relation id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              examples:
                response:
                  "$ref": "#/components/examples/RelationResponse"
              schema:
                "$ref": "#/components/schemas/RelationReadModel"
        '404':
          description: |-
            Returned if the relation does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work packages for the involved work packages
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified relation does not exist.
    delete:
      summary: Delete Relation
      operationId: delete_relation
      tags:
      - Relations
      description: Deletes the relation.
      parameters:
      - description: The unique identifier of the relation resource
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Returned if the relation was deleted successfully. The response
            body is empty.
        '403':
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage work package relations
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to delete this relation.
        '404':
          description: |-
            Returned if the relation does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work packages
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified relation does not exist.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
    patch:
      summary: Update Relation
      operationId: update_relation
      tags:
      - Relations
      description: |-
        When calling this endpoint the client provides a single object, containing the properties and links that it wants
        to change, in the body. It is only allowed to provide properties or links supporting the **write** operation.

        Note that changing the `type` of a relation invariably also changes the respective `reverseType` as well as the
        "name" of it. The returned Relation object will reflect that change. For instance if you change a Relation's
        `type` to "follows" then the `reverseType` will be changed to `precedes`.

        It is not allowed to change a relation's involved work packages.
      parameters:
      - description: Relation ID
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/RelationWriteModel"
            examples:
              request:
                "$ref": "#/components/examples/RelationUpdateRequest"
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/RelationReadModel"
              examples:
                response:
                  "$ref": "#/components/examples/RelationResponse"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '404':
          description: |-
            Returned if the relation does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work packages
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified relation does not exist.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          description: |-
            Returned if:

            - the client tries to modify a read-only property (`PropertyIsReadOnly`)
            - a constraint for a property was violated (`PropertyConstraintViolation`)
            - the client provides a link to an invalid resource (`ResourceTypeMismatch`) or a
              work package that does not exist or for which the client does not have sufficient permissions
              to see it (**required permissions**: `view work packages` for the involved work packages).
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _embedded:
                      details:
                        attribute: lag
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Lag must be a number greater than or equal to 0
  "/api/v3/render/markdown":
    post:
      requestBody:
        required: false
        content:
          text/plain:
            schema:
              type: string
            example: Hello world! [This](http://example.com) **is** markdown!
      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: Renders the Markdown document supplied as plain text in the request
        body into HTML.
      operationId: Preview_Markdown_document
      summary: Preview Markdown document
  "/api/v3/render/plain":
    post:
      requestBody:
        required: false
        content:
          text/plain:
            schema:
              type: string
            example: Hello world! This *is* plain text!
      responses:
        '200':
          content:
            text/html:
              examples:
                response:
                  value: "<p>Hello world! This *is* plain text!</p>\n"
              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: Renders the plain text supplied in the request body into HTML.
      operationId: Preview_plain_document
      summary: Preview plain document
  "/api/v3/revisions/{id}":
    get:
      parameters:
      - description: Revision id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _links:
                      author:
                        href: "/api/v3/users/1"
                      project:
                        href: "/api/v3/projects/1"
                      self:
                        href: "/api/v3/revisions/1"
                      showRevision:
                        href: "/projects/identifier/repository/revision/11f4b07"
                    _type: Revision
                    authorName: Some Developer
                    createdAt: '2015-07-21T13:36:59.454Z'
                    formattedIdentifier: 11f4b07
                    id: 1
                    identifier: 11f4b07dff4f4ce9548a52b7d002daca7cd63ec6
                    message:
                      format: plain
                      html: "<p>This revision provides new features<br/><br/>An elaborate
                        description</p>"
                      raw: |-
                        This revision provides new features

                        An elaborate description
              schema:
                "$ref": "#/components/schemas/RevisionModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified revision does not exist.
          description: |-
            Returned if the revision does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view changesets for the project the repository is created in.

            *Note: A client without sufficient permissions shall not be able to test for the existence of a revision.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
      tags:
      - Revisions
      description: ''
      operationId: View_revision
      summary: View revision
  "/api/v3/reminders":
    get:
      summary: List all active reminders
      operationId: list_reminders
      tags:
      - Reminders
      description: Gets a list of all active reminders for the user.
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                type: object
                required:
                - _type
                - total
                - count
                - _embedded
                properties:
                  _type:
                    type: string
                    enum:
                    - Collection
                  total:
                    type: integer
                    description: The total amount of elements available in the collection.
                    minimum: 0
                  count:
                    type: integer
                    description: Actual amount of elements in this response.
                    minimum: 0
                  _embedded:
                    type: object
                    required:
                    - elements
                    properties:
                      elements:
                        type: array
                        items:
                          "$ref": "#/components/schemas/ReminderModel"
  "/api/v3/reminders/{id}":
    patch:
      summary: Update a reminder
      operationId: update_reminder
      tags:
      - Reminders
      description: |-
        Updates an existing reminder.

        A user can only update their own active reminder.

        **Required permission:** view work packages for the project the reminder is contained in.
      parameters:
      - name: id
        in: path
        description: Reminder ID
        example: 1
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                remindAt:
                  type: string
                  format: date-time
                  description: The date and time when the reminder is due
                note:
                  type: string
                  description: The note of the reminder (optional)
      responses:
        '200':
          description: Reminder updated successfully
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ReminderModel"
        '404':
          description: Returned if the reminder does not exist or the client does
            not have sufficient permissions to see it.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    delete:
      summary: Delete a reminder
      operationId: delete_reminder
      tags:
      - Reminders
      description: |-
        Deletes an existing reminder.

        A user can only delete their own active reminder.

        **Required permission:** view work packages for the project the reminder is contained in.
      parameters:
      - name: id
        in: path
        description: Reminder ID
        example: 1
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Reminder deleted successfully
        '404':
          description: Returned if the reminder does not exist or the client does
            not have sufficient permissions to see it.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/roles":
    get:
      parameters:
      - description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint.
          Currently supported filters are:

          + grantable: filters roles based on whether they are selectable for a membership

          + unit: filters roles based on the unit ('project' or 'system') for which they are selectable for a membership
        example: '[{ "unit": { "operator": "=", "values": ["system"] } }]'
        in: query
        name: filters
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          self:
                            href: "/api/v3/roles/3"
                            title: Manager
                        _type: Role
                        id: 3
                        name: Manager
                      - _links:
                          self:
                            href: "/api/v3/roles/2"
                            title: Anonymous
                        _type: Role
                        id: 2
                        name: Anonymous
                      - _links:
                          self:
                            href: "/api/v3/roles/5"
                            title: Reader
                        _type: Role
                        id: 5
                        name: Reader
                      - _links:
                          self:
                            href: "/api/v3/roles/4"
                            title: Member
                        _type: Role
                        id: 4
                        name: Member
                      - _links:
                          self:
                            href: "/api/v3/roles/1"
                            title: Non member
                        _type: Role
                        id: 1
                        name: Non member
                    _links:
                      self:
                        href: "/api/v3/roles"
                    _type: Collection
                    count: 5
                    total: 5
              schema:
                "$ref": "#/components/schemas/RolesModel"
          description: OK
          headers: {}
      tags:
      - Roles
      description: List all defined roles. This includes built in roles like 'Anonymous'
        and 'Non member'.
      operationId: List_roles
      summary: List roles
  "/api/v3/roles/{id}":
    get:
      parameters:
      - description: Role id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _links:
                      self:
                        href: "/api/v3/roles/3"
                        title: Manager
                    _type: Role
                    id: 3
                    name: Manager
              schema:
                "$ref": "#/components/schemas/RoleModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to view this resource.
          description: |-
            Returned if the client does not have sufficient permissions to see roles.

            **Required permission:** view members **or** manage members
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: Returned if the role does not exist.
          headers: {}
      tags:
      - Roles
      description: Fetch an individual role.
      operationId: View_role
      summary: View role
  "/api/v3/sprints":
    get:
      parameters:
      - description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint.
          Currently supported filters are:

          + definingWorkspace: filters sprints based on the project they are defined in. This is opposed to the projects they are shared with.
        example: '[{ "definingWorkspace": { "operator": "=", "values": ["1"] } }]'
        in: query
        name: filters
        required: false
        schema:
          type: string
      - description: Page number inside the requested collection.
        example: 25
        in: query
        name: offset
        required: false
        schema:
          default: 1
          type: integer
      - description: Number of elements to display per page.
        example: 25
        in: query
        name: pageSize
        required: false
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/SprintCollectionModel"
              examples:
                response:
                  "$ref": "#/components/examples/SprintCollectionResponse"
          description: OK
          headers: {}
      tags:
      - Sprints
      description: List sprints visible to the user. This endpoint supports pagination
        and filtering.
      operationId: List_sprints
      summary: List sprints
  "/api/v3/sprints/{id}":
    get:
      summary: Get sprint
      operationId: get_sprint
      tags:
      - Sprints
      description: Retrieves a sprint defined by its unique identifier.
      parameters:
      - description: Sprint id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/SprintModel"
              examples:
                response:
                  "$ref": "#/components/examples/SprintResponse"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the sprint does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view master backlogs (this will change to view sprints)
  "/api/v3/statuses":
    get:
      summary: List the collection of all statuses
      operationId: list_statuses
      tags:
      - Statuses
      description: Returns a collection of all work package statuses.
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              examples:
                simple status collection:
                  "$ref": "#/components/examples/StatusCollection"
              schema:
                "$ref": "#/components/schemas/StatusCollectionModel"
        '403':
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** view work package (on any project)
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to see the statuses.
  "/api/v3/statuses/{id}":
    get:
      summary: Get a work package status
      operationId: get_status
      tags:
      - Statuses
      description: Returns a work package status by its unique identifier.
      parameters:
      - name: id
        description: Status id
        in: path
        required: true
        schema:
          type: integer
        example: 1
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              examples:
                response:
                  "$ref": "#/components/examples/StatusResponse"
              schema:
                "$ref": "#/components/schemas/StatusModel"
        '403':
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** view work package (on any project)
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to see this status.
        '404':
          description: Returned if the status does not exist.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
  "/api/v3/storages":
    get:
      summary: Get Storages
      operationId: list_storages
      tags:
      - File links
      description: Returns a collection of storages.
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/StorageCollectionModel"
              examples:
                Simple storage collection:
                  "$ref": "#/components/examples/StoragesSimpleCollectionModel"
        '400':
          description: Returned if the client sends invalid request parameters e.g.
            filters
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
                message: Filters Invalid filter does not exist.
    post:
      summary: Creates a storage.
      operationId: create_storage
      tags:
      - File links
      description: |-
        Creates a storage resource. When creating a storage, a confidential OAuth 2 provider application is created
        automatically. The oauth client id and secret of the created OAuth application are returned in the response.

        **IMPORTANT:** This is the only time, the oauth client secret is visible to the consumer. After that, the secret is
        hidden.

        To update the storage with OAuth client credentials, which enable the storage resource to behave as an OAuth 2
        client against an external OAuth 2 provider application, another request must be made to create those, see
        `POST /api/v3/storages/{id}/oauth_client_credentials`.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/StorageWriteModel"
      responses:
        '201':
          description: Created
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/StorageReadModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** Depends on the page the grid is defined for.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
  "/api/v3/storages/{id}":
    get:
      summary: Get a storage
      operationId: get_storage
      tags:
      - File links
      description: |-
        Gets a storage resource. As a side effect, a live connection to the storages origin is established to retrieve
        connection state data.
      parameters:
      - name: id
        description: Storage id
        in: path
        required: true
        schema:
          type: integer
        example: 1337
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/StorageReadModel"
              examples:
                Nextcloud storage:
                  "$ref": "#/components/examples/StorageNextcloudResponse"
                Freshly created Nextcloud storage:
                  "$ref": "#/components/examples/StorageNextcloudResponseForCreation"
                OneDrive storage:
                  "$ref": "#/components/examples/StorageOneDriveResponse"
                Incomplete OneDrive storage:
                  "$ref": "#/components/examples/StorageOneDriveIncompleteResponse"
                Unauthorized Nextcloud storage:
                  "$ref": "#/components/examples/StorageNextcloudUnauthorizedResponse"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the storage does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view file links
    patch:
      summary: Update a storage
      operationId: update_storage
      tags:
      - File links
      description: |-
        Updates a storage resource. Only data that is not generated by the server can be updated. This excludes the OAuth 2
        application data.
      parameters:
      - name: id
        description: Storage id
        in: path
        required: true
        schema:
          type: integer
        example: 1337
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/StorageWriteModel"
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/StorageReadModel"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** admin
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the storage does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view file links
    delete:
      summary: Delete a storage
      operationId: delete_storage
      tags:
      - File links
      description: |-
        Deletes a storage resource. This also deletes all related records, like the created oauth application, client, and
        any file links created within this storage.
      parameters:
      - name: id
        description: Storage id
        in: path
        required: true
        schema:
          type: integer
        example: 1337
      responses:
        '204':
          description: No content
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** admin
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the storage does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view file links
  "/api/v3/storages/{id}/files":
    get:
      summary: Gets files of a storage.
      operationId: get_storage_files
      tags:
      - File links
      description: |-
        Gets a collection of files from a storage.

        If no `parent` context is given, the result is the content of the document root. With `parent` context given, the
        result contains the collections of files/directories from within the given parent file id.

        If given `parent` context is no directory, `400 Bad Request` is returned.
      parameters:
      - name: id
        description: Storage id
        in: path
        required: true
        schema:
          type: integer
        example: 1337
      - name: parent
        description: Parent file identification
        in: query
        required: false
        schema:
          type: string
        example: "/my/data"
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/StorageFilesModel"
        '400':
          description: Returned if the given parent parameter value does not refer
            to a directory.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
                message: The given parent is not a directory.
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned in either of those cases:
            - if the storage does not exist or the client does not have sufficient permissions to see it

              **Required permission:** view file links
            - if the document root file identification does not exist on the storage
  "/api/v3/storages/{id}/files/prepare_upload":
    post:
      summary: Preparation of a direct upload of a file to the given storage.
      operationId: prepare_storage_file_upload
      tags:
      - File links
      description: |-
        Executes a request that prepares a link for a direct upload to the storage.

        The background here is, that the client needs to make a direct request to the storage instance for file uploading,
        but should not get access to the credentials, which are stored in the backend. The response contains a link object,
        that enables the client to execute a file upload without the real credentials.
      parameters:
      - name: id
        description: Storage id
        in: path
        required: true
        schema:
          type: integer
        example: 1337
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/StorageFileUploadPreparationModel"
      responses:
        '201':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/StorageFileUploadLinkModel"
        '400':
          description: Returned if the given parent parameter value does not refer
            to a directory.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
                message: The given parent is not a directory.
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage file links
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the storage does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view file links
        '500':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                outbound request failed:
                  description: |-
                    This error is returned, if the outbound request to the file storage failed with a 404, e.g. if the
                    upload location is not available.
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:OutboundRequest:NotFound
                    message: An outbound request to another resource has failed with
                      status code 404.
                enterprise token missing:
                  description: |-
                    This error is returned, if there is no Enterprise token available. The file upload to that storage is
                    only available in an Enterprise edition.
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingEnterpriseToken
                    message: The request cannot be handled due to invalid or missing
                      Enterprise token.
          description: Returned if the outbound request to the storage has failed
            with any reason.
  "/api/v3/storages/{id}/folders":
    post:
      summary: Creation of a new folder
      operationId: create_storage_folder
      tags:
      - File links
      description: Creates a new folder under the given parent
      parameters:
      - name: id
        description: Storage id
        in: path
        required: true
        schema:
          type: integer
        example: 1337
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/StorageFolderWriteModel"
            examples:
              Valid example:
                "$ref": "#/components/examples/StorageCreateFolderRequestBody"
      responses:
        '201':
          description: Created
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/StorageFileModel"
        '400':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
                message: The given parent is not a directory.
          description: Returned if the request is missing a required parameter.
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage file links
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the storage does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view file links
  "/api/v3/storages/{id}/oauth_client_credentials":
    post:
      summary: Creates an oauth client credentials object for a storage.
      operationId: create_storage_oauth_credentials
      tags:
      - File links
      description: |-
        Inserts the OAuth 2 credentials into the storage, to allow the storage to act as an OAuth 2 client. Calling this
        endpoint on a storage that already contains OAuth 2 client credentials will replace them.
      parameters:
      - name: id
        description: Storage id
        in: path
        required: true
        schema:
          type: integer
        example: 1337
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/OAuthClientCredentialsWriteModel"
      responses:
        '201':
          description: Created
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/StorageReadModel"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** admin
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the storage does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view file links
  "/api/v3/storages/{id}/open":
    get:
      summary: Open the storage
      operationId: open_storage
      tags:
      - File Links
      description: |-
        Gets a redirect to the location of the storage's remote origin. The storage's files root should be the target
        location.
      parameters:
      - name: id
        description: Storage id
        in: path
        required: true
        schema:
          type: integer
        example: 1337
      responses:
        '303':
          description: Redirect
          headers:
            Location:
              schema:
                type: string
                format: uri
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the storage does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view file links
  "/api/v3/th_queries/{id}":
    get:
      summary: View a TH query with results
      operationId: get_th_query
      tags:
      - TH Queries
      description: |-
        Returns a saved query with work package results in `_embedded.results`. Overrides apply only
        to this response and are not saved. Invalid parts of the stored query are removed before applying
        request parameters. Invalid client overrides produce an error unless `valid_subset=true`.

        The query is loaded by ID without a separate ownership or public-query check. The result work
        packages remain scoped to the caller's visibility. Response links use the standard query and
        work package endpoints, including `/api/v3/queries/{id}` for the query self link.
      parameters:
      - name: id
        in: path
        required: true
        description: Saved query ID.
        schema:
          type: integer
        example: 7
      - name: filters
        description: JSON filter conditions replacing the query filters for this request.
          Use [] to remove all filters. Accepts the same filters as the work packages
          endpoint.
        example: '[{ "assignee": { "operator": "=", "values": ["1", "5"] } }]'
        in: query
        required: false
        schema:
          type: string
      - name: offset
        description: Page number inside the queries' result collection of work packages.
        example: 25
        in: query
        required: false
        schema:
          default: 1
          type: integer
      - name: pageSize
        description: Number of elements to display per page for the queries' result
          collection of work packages.
        example: 25
        in: query
        required: false
        schema:
          type: integer
      - name: columns[]
        description: |-
          Selected columns for the table view. Repeat the parameter for every column,
          e.g. `columns[]=type&columns[]=priority`.
        example:
        - type
        - priority
        in: query
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: sortBy
        description: JSON sort criteria for the result work packages, overriding the
          query configuration for this request.
        example: '[["status", "asc"]]'
        in: query
        required: false
        schema:
          type: string
      - name: groupBy
        description: Column used to group the result work packages. An empty value
          clears the grouping.
        example: status
        in: query
        required: false
        schema:
          type: string
      - name: showSums
        description: Whether to calculate sums for properties that support them.
        example: true
        in: query
        required: false
        schema:
          type: boolean
      - name: timestamps
        description: 'Indicates the timestamps to filter by when showing changed attributes
          on work packages. Values can be either ISO8601 dates, ISO8601 durations
          and the following relative date keywords: "oneDayAgo@HH:MM+HH:MM", "lastWorkingDay@HH:MM+HH:MM",
          "oneWeekAgo@HH:MM+HH:MM", "oneMonthAgo@HH:MM+HH:MM". The first "HH:MM" part
          represents the zero paded hours and minutes. The last "+HH:MM" part represents
          the timezone offset from UTC associated with the time, the offset can be
          positive or negative e.g."oneDayAgo@01:00+01:00", "oneDayAgo@01:00-01:00".
          Values older than 1 day are accepted only with valid Enterprise Token available.

          '
        example: 2023-01-01,P-1Y,PT0S,lastWorkingDay@12:00
        in: query
        required: false
        schema:
          type: string
      - name: timelineVisible
        description: Indicates whether the timeline should be shown.
        example: true
        in: query
        required: false
        schema:
          type: boolean
      - name: timelineLabels
        description: Overridden labels in the timeline view
        example: "{}"
        in: query
        required: false
        schema:
          type: string
      - name: highlightingMode
        description: Highlighting mode for the table view.
        example: inline
        in: query
        required: false
        schema:
          type: string
      - name: highlightedAttributes[]
        description: |-
          Highlighted attributes mode for the table view when `highlightingMode` is `inline`.
          Repeat the parameter for every attribute, e.g.
          `highlightedAttributes[]=type&highlightedAttributes[]=priority`.
          When omitted, all highlightable attributes will be returned as `highlightedAttributes`.
        example:
        - type
        - priority
        in: query
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: showHierarchies
        description: Indicates whether the hierarchy mode should be enabled.
        example: true
        in: query
        required: false
        schema:
          type: boolean
      - in: query
        required: false
        name: includeSubprojects
        description: Include work packages from subprojects of the query project.
        schema:
          type: boolean
      - in: query
        required: false
        name: includeAllMembersAssignedProjects
        description: Include projects with work assigned to members of the query project.
          Work package visibility still applies.
        schema:
          type: boolean
      - in: query
        required: false
        name: timelineZoomLevel
        description: Override the timeline zoom level.
        schema:
          type: string
        example: days
      - in: query
        required: false
        name: displayRepresentation
        description: Override the query display representation.
        schema:
          type: string
        example: table
      - in: query
        required: false
        name: select
        description: Comma-separated properties to include in the embedded work package
          results. Nested properties use slash-separated paths.
        schema:
          type: string
        example: id,subject
      - name: valid_subset
        in: query
        required: false
        description: Remove invalid parts of client query overrides instead of returning
          an invalid-query error. Does not bypass work package visibility.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/QueryModel"
        '400':
          description: Returned if query parameters are malformed or the resulting
            query is invalid.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '401':
          description: Returned if authentication is required and the client is not
            authenticated, or credentials are invalid.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '404':
          description: Returned if the query does not exist.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/time_entries":
    get:
      summary: List time entries
      operationId: list_time_entries
      tags:
      - Time entries
      description: |-
        Lists time entries. The time entries returned depend on the filters
        provided and also on the permission of the requesting user.
      parameters:
      - name: offset
        description: Page number inside the requested collection.
        example: 25
        in: query
        required: false
        schema:
          default: 1
          type: integer
      - name: pageSize
        description: Number of elements to display per page.
        example: 25
        in: query
        required: false
        schema:
          type: integer
      - name: sortBy
        description: |-
          JSON specifying sort criteria.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported sorts are:

          + id: Sort by primary key

          + hours: Sort by logged hours

          + spent_on: Sort by spent on date

          + created_at: Sort by time entry creation datetime

          + updated_at: Sort by the time the time entry was updated last
        example: '[["spent_on", "asc"]]'
        in: query
        required: false
        schema:
          default: '["spent_on", "asc"]'
          type: string
      - name: filters
        description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported filters are:

          + entity_type: Filter time entries depending on the entity they are logged on. Can either be `WorkPackage` or `Meeting`.

          + entity_id: Filter time entries for the specified entity IDs.

          + project_id: Filter time entries by project

          + user_id: Filter time entries by users

          + ongoing: Filter to only recevie ongoing timers

          + spent_on: Filter time entries by spent on date

          + created_at: Filter time entries by creation datetime

          + updated_at: Filter time entries by the last time they where updated

          + activity_id: Filter time entries by time entry activity
        example: '[{ "entity_type": { "operator": "=", "values": ["WorkPackage"] }},
          { "entity_id": { "operator": "=", "values": ["1", "2"] } }, { "project":
          { "operator": "=", "values": ["1"] } }]'
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/TimeEntryCollectionModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          description: Returned if the client is not logged in and login is required.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to view this resource.
    post:
      summary: Create time entry
      tags:
      - Time entries
      description: |-
        Creates a new time entry applying the attributes provided in the body.
        Please note that while there is a fixed set of attributes, custom fields can extend
        a time entries' attributes and are accepted by the endpoint.
      operationId: create_time_entry
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/TimeEntryWriteModel"
      responses:
        '201':
          description: Created
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/TimeEntryModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** Log time
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _embedded:
                      details:
                        attribute: workPackage
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Work package is invalid.
  "/api/v3/time_entries/th_keyin":
    post:
      summary: Submit TH key-in time entries
      operationId: submit_time_entries_th_keyin
      tags:
      - Time entries
      description: |-
        Submits Tianhua key-in time entries for the authenticated user.

        The request must contain at least one entry type:

        - `projectTimeEntries` to submit time on assigned work packages.
        - `nonProjectTimeEntries` to submit non-project activities.
        - Both arrays can be submitted together, matching the TH key-in form behavior.

        The submitted `date` must be today or one of the eight previous eligible key-in days.
        When `keyinUserId` is provided, entries belong to that user while `logged_by_id` remains the authenticated user's ID.
        Set `rejectReKeying` to `true` only when re-keying rejected entries outside that normal date window.
        Project entries require the authenticated user to have permission to log own time on each submitted work package.
        Project time entries created by this endpoint are stored with `time_entries.new_split_keyin` set to `true`.
        Non-project entries support writable TH activities only; `take_vacation` is read-only.
        The owner's combined project and non-project hours for the date, including saved entries
        that are not replaced by this request and read-only vacation hours, must not exceed 24.
        Exactly 24 hours is allowed. A submission exceeding the limit returns 422 and saves no changes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - date
              properties:
                date:
                  type: string
                  format: date
                  description: ISO 8601 date to submit.
                  example: '2026-03-17'
                keyinUserId:
                  type: integer
                  description: User ID that owns the submitted entries. Defaults to
                    the authenticated user.
                  example: 294
                rejectReKeying:
                  type: boolean
                  description: Set to `true` to allow rejected-entry re-keying outside
                    the normal key-in date window.
                  default: false
                  example: true
                projectTimeEntries:
                  type: array
                  description: Project time entries.
                  items:
                    type: object
                    required:
                    - workPackageId
                    properties:
                      workPackageId:
                        type: integer
                        description: Assigned work package ID.
                        example: 1528
                      statusId:
                        type: integer
                        description: Optional new status ID. Defaults to the work
                          package's current status.
                        example: 1
                      drawingHours:
                        type: number
                        format: float
                        description: Design or drawing hours.
                        example: 4.5
                      discussingHours:
                        type: number
                        format: float
                        description: External communication hours.
                        example: 1
                      travelHours:
                        type: number
                        format: float
                        description: Travel hours.
                        example: 0.5
                      comments:
                        type: string
                        description: Optional comment stored on the submitted time
                          entries.
                        example: Daily update
                nonProjectTimeEntries:
                  type: array
                  description: Non-project time entries.
                  items:
                    type: object
                    required:
                    - activity
                    properties:
                      activity:
                        type: string
                        enum:
                        - leave_in_lieu
                        - training
                        - research
                        - marketing
                        - department_manage
                        description: Non-project activity name. `take_vacation` is
                          read-only and cannot be submitted.
                        example: training
                      hours:
                        type: number
                        format: float
                        example: 3.5
                      comments:
                        type: string
                        example: Internal workshop
              anyOf:
              - required:
                - projectTimeEntries
              - required:
                - nonProjectTimeEntries
            examples:
              project:
                value:
                  date: '2026-03-17'
                  projectTimeEntries:
                  - workPackageId: 1528
                    drawingHours: 4.5
                    discussingHours: 1
                    travelHours: 0.5
                    comments: Daily update
              nonProject:
                value:
                  date: '2026-03-17'
                  nonProjectTimeEntries:
                  - activity: training
                    hours: 3.5
                    comments: Internal workshop
              mixed:
                value:
                  date: '2026-03-17'
                  projectTimeEntries:
                  - workPackageId: 1528
                    drawingHours: 4.5
                    comments: Daily update
                  nonProjectTimeEntries:
                  - activity: training
                    hours: 1
                    comments: Internal workshop
      responses:
        '200':
          description: Submitted
          content:
            application/hal+json:
              schema:
                type: object
                required:
                - _type
                - isSuccess
                - entryType
                - fillingDay
                - submittedCount
                properties:
                  _type:
                    type: string
                    enum:
                    - ThKeyinSubmission
                  isSuccess:
                    type: boolean
                    example: true
                  entryType:
                    type: string
                    enum:
                    - project
                    - non_project
                    - mixed
                  fillingDay:
                    type: string
                    format: date
                    example: '2026-03-17'
                  submittedCount:
                    type: integer
                    example: 1
              example:
                _type: ThKeyinSubmission
                isSuccess: true
                entryType: project
                fillingDay: '2026-03-17'
                submittedCount: 1
        '400':
          description: Returned if the request body is missing required key-in data
            or contains invalid date/hour formats.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:BadRequest
                message: 'Bad request: date is required'
        '401':
          description: Returned if the client is not authenticated.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                message: You need to be authenticated to access this resource.
        '403':
          description: Returned if the client does not have sufficient permissions.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          description: Returned if the key-in payload violates a submission rule.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:UnprocessableContent
                message: The total non-project hours for one day cannot exceed 24
                  hours
  "/api/v3/time_entries/{id}/form":
    post:
      parameters:
      - description: Time entries activity id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/TimeEntryFormModel"
          description: OK
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions to edit the time entry.

            **Required permission:** *edit time entries* for every time entry of a project, or *edit own time entries* for time entries belonging to the user.
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the time entry does not exist or if the client does not have sufficient permissions to view it.

            **Required permission** `view time entries` in the project the time entry is assigned to or `view own time entries` for time entries belonging to the user
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
      tags:
      - Time Entries
      description: ''
      operationId: Time_entry_update_form
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/TimeEntryWriteModel"
      summary: Time entry update form
  "/api/v3/time_entries/activity/{id}":
    get:
      summary: View time entries activity
      operationId: get_time_entries_activity
      tags:
      - Time entry activities
      description: Fetches the time entry activity resource by the given id.
      parameters:
      - name: id
        description: Time entries activity id
        in: path
        example: 1
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/TimeEntryActivityModel"
        '404':
          description: |-
            Returned if the activity does not exist or if the user does not have permission to view them.

            **Required permission** `view time entries`, `log time`, `edit time entries`, `edit own time entries` or
            `manage project activities` in any project
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
  "/api/v3/time_entries/available_projects":
    get:
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _type: Project...
                      - _type: Project...
                    _links:
                      self:
                        href: "/api/v3/time_entries/available_projects"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/Available_projects_for_time_entriesModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** *log time*, *edit time entries* or *edit own time entries* in any project
          headers: {}
      tags:
      - Time Entries
      description: Gets a list of projects in which a time entry can be created in
        or be assigned to on update. The list contains all projects in which the user
        issuing the request has the necessary permissions.
      operationId: Available_projects_for_time_entries
      summary: Available projects for time entries
  "/api/v3/time_entries/form":
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/TimeEntryWriteModel"
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/TimeEntryFormModel"
          description: OK
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** *log time* in any project
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
      tags:
      - Time Entries
      description: ''
      operationId: Time_entry_create_form
      summary: Time entry create form
  "/api/v3/time_entries/schema":
    get:
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _dependencies: []
                    _links:
                      self:
                        href: "/api/v3/time_entries/schema"
                    _type: Schema
                    activity:
                      _links: {}
                      hasDefault: true
                      location: _links
                      name: Activity
                      required: true
                      type: TimeEntriesActivity
                      writable: true
                    createdAt:
                      hasDefault: false
                      name: Created on
                      options: {}
                      required: true
                      type: DateTime
                      writable: false
                    customField29:
                      hasDefault: false
                      name: sfsdfsdfsdfsdfdsf
                      options:
                        rtl:
                      required: false
                      type: String
                      writable: true
                    hours:
                      hasDefault: false
                      name: Hours
                      options: {}
                      required: true
                      type: Duration
                      writable: true
                    approvedHours:
                      hasDefault: false
                      name: Approved Hours
                      options: {}
                      required: false
                      type: Duration
                      writable: true
                    fromThKeyin:
                      hasDefault: false
                      name: From TH Keyin
                      options: {}
                      required: false
                      type: Boolean
                      writable: true
                    id:
                      hasDefault: false
                      name: ID
                      options: {}
                      required: true
                      type: Integer
                      writable: false
                    project:
                      _links: {}
                      hasDefault: false
                      location: _links
                      name: Project
                      required: false
                      type: Project
                      writable: true
                    ongoing:
                      hasDefault: false
                      name: Ongoing
                      options: {}
                      required: false
                      type: Boolean
                      writable: true
                    spentOn:
                      hasDefault: false
                      name: Date
                      options: {}
                      required: true
                      type: Date
                      writable: true
                    updatedAt:
                      hasDefault: false
                      name: Updated on
                      options: {}
                      required: true
                      type: DateTime
                      writable: false
                    user:
                      hasDefault: false
                      name: User
                      options: {}
                      required: true
                      type: User
                      writable: false
                    workPackage:
                      _links: {}
                      hasDefault: false
                      location: _links
                      name: Work package
                      required: false
                      type: WorkPackage
                      writable: true
              schema:
                "$ref": "#/components/schemas/View_time_entry_schemaModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions to see the schema.

            **Required permission:** *log time* or *view time entries* or *edit time entries* or *edit own time entries* on any project
          headers: {}
      tags:
      - Time Entries
      description: ''
      operationId: View_time_entry_schema
      summary: View time entry schema
  "/api/v3/time_entries/{id}":
    delete:
      summary: Delete time entry
      tags:
      - Time entries
      description: Permanently deletes the specified time entry.
      operationId: delete_time_entry
      parameters:
      - name: id
        description: Time entry id
        example: 1
        in: path
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Returned if the time entry was deleted successfully.
        '403':
          description: Returned if the client does not have sufficient permissions
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
        '404':
          description: |-
            Returned if the time entry does not exist or if the user does not have sufficient permissions to see the time entry.

            **Required permission** `view time entries` in the project the time entry is assigned to or `view own time entries` for time entries belonging to the user
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
    get:
      summary: Get time entry
      tags:
      - Time entries
      description: Retrieves a single time entry identified by the given id.
      operationId: get_time_entry
      parameters:
      - name: id
        description: time entry id
        example: 1
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/TimeEntryModel"
        '404':
          description: |-
            Returned if the time entry does not exist or if the user does not have permission to view them.

            **Required permission**
            - `view time entries` in the project the time entry is assigned to or
            - `view own time entries` for time entries belonging to the user
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
    patch:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/TimeEntryWriteModel"
      summary: update time entry
      tags:
      - Time Entries
      description: |-
        Updates the given time entry by applying the attributes provided in
        the body. Please note that while there is a fixed set of attributes, custom fields
        can extend a time entries' attributes and are accepted by the endpoint.
      operationId: update_time_entry
      parameters:
      - name: id
        description: Time entry id
        example: 1
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/TimeEntryModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** Edit (own) time entries, depending on what time entry is being modified.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _embedded:
                  details:
                    attribute: workPackage
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: Work package is invalid.
  "/api/v3/types":
    get:
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          self:
                            href: "/api/v3/types/1"
                        _type: Type
                        color: "#ff0000"
                        createdAt: '2014-05-21T08:51:20.396Z'
                        id: 1
                        isDefault: true
                        isMilestone: false
                        name: Bug
                        position: 1
                        updatedAt: '2014-05-21T08:51:20.396Z'
                      - _links:
                          self:
                            href: "/api/v3/types/2"
                        _type: Type
                        color: "#888"
                        createdAt: '2014-05-21T08:51:20.396Z'
                        id: 2
                        isDefault: false
                        isMilestone: false
                        name: Feature
                        position: 2
                        updatedAt: '2014-05-21T08:51:20.396Z'
                    _links:
                      self:
                        href: "/api/v3/types"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/TypesModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to see the types.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** view work package or manage types (on any project)
          headers: {}
      tags:
      - Types
      description: ''
      operationId: List_all_Types
      summary: List all Types
  "/api/v3/types/{id}":
    get:
      parameters:
      - description: Type id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _links:
                      self:
                        href: "/api/v3/types/1"
                    _type: Type
                    color: "#ff0000"
                    createdAt: '2014-05-21T08:51:20.396Z'
                    id: 1
                    isDefault: true
                    isMilestone: false
                    name: Bug
                    position: 1
                    updatedAt: '2014-05-21T08:51:20.396Z'
              schema:
                "$ref": "#/components/schemas/TypeModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to see this type.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** view work package or manage types (on any project)
          headers: {}
      tags:
      - Types
      description: ''
      operationId: View_Type
      summary: View Type
  "/api/v3/users":
    get:
      summary: List Users
      operationId: list_Users
      description: |-
        Lists users. Only administrators or users with the following global permission can access this resource:
        - `manage_user`
      tags:
      - Users
      - Principals
      parameters:
      - description: Page number inside the requested collection.
        example: 25
        in: query
        name: offset
        required: false
        schema:
          default: 1
          type: integer
      - description: Number of elements to display per page.
        example: 25
        in: query
        name: pageSize
        required: false
        schema:
          type: integer
      - description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/)
          endpoint. Currently supported filters are:

          + status: Status the user has

          + group: Name of the group in which to-be-listed users are members.

          + name: Filter users in whose first or last names, or email addresses the given string occurs.

          + login: User's login
        example: '[{ "status": { "operator": "=", "values": ["invited"] } }, { "group":
          { "operator": "=", "values": ["1"] } }, { "name": { "operator": "=", "values":
          ["h.wurst@openproject.com"] } }]'
        in: query
        name: filters
        required: false
        schema:
          type: string
      - description: |-
          JSON specifying sort criteria.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint.
        example: '[["status", "asc"]]'
        in: query
        name: sortBy
        required: false
        schema:
          type: string
      - description: Comma separated list of properties to include.
        example: total,elements/name,elements/self,self
        in: query
        name: select
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/UserCollectionModel"
          description: OK
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to list users.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** Administrator or any of: 'manage_members', 'manage_user', 'share_work_packages'.
    post:
      summary: Create User
      operationId: create_user
      tags:
      - Users
      - Principals
      description: |-
        Creates a new user. Only administrators and users with manage_user global permission are allowed to do so.
        When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body.

        Valid values for `status`:

        1) "active" - In this case a password has to be provided in addition to the other attributes.

        2) "invited" - In this case nothing but the email address is required. The rest is optional. An invitation will be sent to the user.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UserCreateModel"
      responses:
        '201':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/UserModel"
          description: Created
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to create new users.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** Administrator
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _embedded:
                  details:
                    attribute: email
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: The email address is already taken.
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
  "/api/v3/users/schema":
    get:
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _dependencies: []
                    _links:
                      self:
                        href: "/api/v3/users/schema"
                    _type: Schema
                    admin:
                      hasDefault: false
                      name: Administrator
                      options: {}
                      required: false
                      type: Boolean
                      writable: true
                    avatar:
                      hasDefault: false
                      name: Avatar
                      options: {}
                      required: false
                      type: String
                      writable: false
                    createdAt:
                      hasDefault: false
                      name: Created on
                      options: {}
                      required: true
                      type: DateTime
                      writable: false
                    customField1:
                      hasDefault: false
                      name: User String CF
                      required: false
                      type: String
                      writable: true
                    customField2:
                      hasDefault: false
                      location: _links
                      name: User List cf
                      required: false
                      type: CustomOption
                      writable: true
                    firstName:
                      hasDefault: false
                      maxLength: 255
                      minLength: 1
                      name: First name
                      options: {}
                      required: true
                      type: String
                      writable: false
                    id:
                      hasDefault: false
                      name: ID
                      options: {}
                      required: true
                      type: Integer
                      writable: false
                    identityUrl:
                      hasDefault: false
                      name: Identity url
                      options: {}
                      required: false
                      type: String
                      writable: true
                    language:
                      hasDefault: false
                      name: Language
                      options: {}
                      required: false
                      type: String
                      writable: true
                    lastName:
                      hasDefault: false
                      maxLength: 255
                      minLength: 1
                      name: Last name
                      options: {}
                      required: true
                      type: String
                      writable: false
                    login:
                      hasDefault: false
                      maxLength: 255
                      minLength: 1
                      name: Username
                      options: {}
                      required: true
                      type: String
                      writable: true
                    mail:
                      hasDefault: false
                      maxLength: 255
                      minLength: 1
                      name: Email
                      options: {}
                      required: true
                      type: String
                      writable: true
                    password:
                      hasDefault: false
                      name: Password
                      options: {}
                      required: false
                      type: Password
                      writable: false
                    status:
                      hasDefault: false
                      name: Status
                      options: {}
                      required: false
                      type: String
                      writable: true
                    updatedAt:
                      hasDefault: false
                      name: Updated on
                      options: {}
                      required: true
                      type: DateTime
                      writable: false
              schema:
                "$ref": "#/components/schemas/View_user_schemaModel"
          description: OK
          headers: {}
      tags:
      - Users
      description: The schema response use two exemplary custom fields that extend
        the schema response. Depending on your instance and custom field configuration,
        the response will look somewhat different.
      operationId: View_user_schema
      summary: View user schema
  "/api/v3/users/{id}":
    delete:
      summary: Delete user
      operationId: delete_user
      description: Permanently deletes the specified user account.
      tags:
      - Users
      - Principals
      parameters:
      - description: User id. Use `me` to reference current user, if any.
        example: '1'
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '202':
          description: |-
            Returned if the account was deleted successfully.

            Note that the response body is empty as of now. In future versions of the API a body
            *might* be returned, indicating the progress of deletion.
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to delete the account of this user.
          description: |-
            Returned if the client does not have sufficient permissions or if deletion of users was disabled in the instance wide settings.

            **Required permission:** Administrators only (exception: users might be able to delete their own accounts)
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified user does not exist.
          description: Returned if the user does not exist.
    get:
      summary: View user
      operationId: view_user
      description: ''
      tags:
      - Users
      - Principals
      parameters:
      - description: User id. Use `me` to reference current user, if any.
        example: '1'
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/UserModel"
              examples:
                user response:
                  "$ref": "#/components/examples/UserResponse"
          description: OK
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified user does not exist or you do not have permission
                  to view them.
          description: |-
            Returned if the user does not exist or if the API user does not have permission to view them.

            **Required permission** The user needs to be locked in if the installation is configured to prevent anonymous access
    patch:
      summary: Update user
      operationId: update_user
      tags:
      - Users
      - Principals
      description: |-
        Updates the user's writable attributes.
        When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body.

        Password updates for self-service account changes require both `password` and `currentPassword`.
      parameters:
      - description: User id. Use `me` to reference current user, if any.
        example: '1'
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UserUpdateModel"
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/UserModel"
          description: OK
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to update the account of this user.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** Administrators, manage_user global permission
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified user does not exist or you do not have permission
                  to view them.
          description: |-
            Returned if the user does not exist or if the API user does not have the necessary permissions to update it.

            **Required permission:** Administrators only (exception: users may update their own accounts)
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                email constraint violation:
                  value:
                    _embedded:
                      details:
                        attribute: email
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: The email address is already taken.
                invalid current password:
                  value:
                    _embedded:
                      details:
                        attribute: currentPassword
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Current password is invalid.
          description: |-
            Returned if:

            * the client tries to modify a read-only property (`PropertyIsReadOnly`)

            * a constraint for a property was violated (`PropertyConstraintViolation`)
  "/api/v3/users/{id}/form":
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UserUpdateModel"
      parameters:
      - description: User id. Use `me` to reference current user, if any.
        example: '1'
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/UserFormModel"
          description: OK
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage_user global permission
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the request user can not be found.

            *Note: A client without sufficient permissions shall not be able to test for the existence of
            a membership. That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
      tags:
      - Users
      description: |-
        Validates a user update payload.

        For self password changes, provide both `password` and `currentPassword`.
      operationId: User_update_form
      summary: User update form
  "/api/v3/users/{id}/lock":
    delete:
      summary: Unlock user
      operationId: unlock_user
      tags:
      - Users
      parameters:
      - description: User id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/UserModel"
          description: OK
        '400':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidUserStatusTransition
                message: The current user account status does not allow this operation.
          description: |-
            Returned if the client tries to unlock a user account whose current status does not allow this transition.

            **Required permission:** Administrators only
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to unlock the account of this user.
          description: |-
            Returned if the client does not have sufficient permissions for unlocking a user.

            **Required permission:** Administrators only
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified user does not exist.
          description: Returned if the user does not exist.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
    post:
      summary: Lock user
      operationId: lock_user
      tags:
      - Users
      parameters:
      - description: User id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/UserModel"
          description: OK
        '400':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidUserStatusTransition
                message: The current user account status does not allow this operation.
          description: |-
            Returned if the client tries to lock a user account whose current status does not allow this transition.

            **Required permission:** Administrators only
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to lock the account of this user.
          description: |-
            Returned if the client does not have sufficient permissions for locking a user.

            **Required permission:** Administrators only
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified user does not exist.
          description: Returned if the user does not exist.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
  "/api/v3/users/{id}/non_working_times":
    get:
      summary: List personal non-working times for a user
      operationId: list_user_non_working_times
      tags:
      - User Working Times
      description: |-
        Returns all personal non-working times for the given user, ordered by start date ascending.

        Personal non-working times mark date ranges as non-working for a user
        (e.g., a local holiday or personal day off not covered by the system-wide non-working days).

        **Required permissions:**
        - Administrators can view non-working days for any user.
        - Users with the global `manage_own_working_times` permission can view their own records.
        - Users with the global `manage_working_times` permission can view non-working days for any user.

        Use `me` as the `id` to reference the current user.
      parameters:
      - name: id
        in: path
        required: true
        description: User id. Use `me` to reference the current user.
        schema:
          type: string
        example: '42'
      - name: year
        in: query
        required: false
        description: Filter results to the given year. Defaults to the current year
          if not provided.
        schema:
          type: integer
        example: 2025
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/UserNonWorkingTimeCollectionModel"
        '401':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                message: You need to be authenticated to access this resource.
          description: Returned if the client is not authenticated.
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified user does not exist or you do not have permission
                  to view them.
          description: Returned if the user does not exist or is not visible to the
            requesting user.
    post:
      summary: Create a personal non-working day for a user
      operationId: create_user_non_working_time
      tags:
      - User Working Times
      description: |-
        Creates a personal non-working time range for the given user.

        The date range must not overlap with an existing non-working time record for the same user.

        **Required permissions:**
        - Administrators can create non-working days for any user.
        - Users with the global `manage_own_working_times` permission can create records for themselves.
        - Users with the global `manage_working_times` permission can create non-working days for any user.

        Use `me` as the `id` to reference the current user.
      parameters:
      - name: id
        in: path
        required: true
        description: User id. Use `me` to reference the current user.
        schema:
          type: string
        example: '42'
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UserNonWorkingTimeModel"
            example:
              startDate: '2025-06-16'
              endDate: '2025-06-20'
      responses:
        '201':
          description: Created
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/UserNonWorkingTimeModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '401':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                message: You need to be authenticated to access this resource.
          description: Returned if the client is not authenticated.
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** `manage_working_times` globally (for other users) or
            `manage_own_working_times` globally (for own records).
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified user does not exist or you do not have permission
                  to view them.
          description: Returned if the user does not exist or is not visible to the
            requesting user.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: Validation failed.
          description: |-
            Returned if the request body contains invalid parameters, or if the date range
            overlaps with an existing non-working time record for the user.
  "/api/v3/users/{id}/non_working_times/{non_working_time_id}":
    get:
      summary: View a personal non-working time record
      operationId: view_user_non_working_time
      tags:
      - User Working Times
      description: |-
        Returns a single personal non-working time record for the given user.

        **Required permissions:**
        - Administrators can view non-working time records for any user.
        - Users with the global `manage_own_working_times` permission can view their own records.
        - Users with the global `manage_working_times` permission can view non-working time records for any user.

        Use `me` as the `id` to reference the current user.
      parameters:
      - name: id
        in: path
        required: true
        description: User id. Use `me` to reference the current user.
        schema:
          type: string
        example: '42'
      - name: non_working_time_id
        in: path
        required: true
        description: The id of the personal non-working time record.
        schema:
          type: integer
        example: 7
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/UserNonWorkingTimeModel"
        '401':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                message: You need to be authenticated to access this resource.
          description: Returned if the client is not authenticated.
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the user or non-working time record does not exist,
            or if the requesting user does not have permission to view it.
    patch:
      summary: Update a personal non-working time record
      operationId: update_user_non_working_time
      tags:
      - User Working Times
      description: |-
        Updates the given personal non-working time record.

        **Required permissions:**
        - Administrators can update non-working time records for any user.
        - Users with the global `manage_own_working_times` permission can update their own records.
        - Users with the global `manage_working_times` permission can update non-working time records for any user.

        Use `me` as the `id` to reference the current user.
      parameters:
      - name: id
        in: path
        required: true
        description: User id. Use `me` to reference the current user.
        schema:
          type: string
        example: '42'
      - name: non_working_time_id
        in: path
        required: true
        description: The id of the personal non-working time record.
        schema:
          type: integer
        example: 7
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UserNonWorkingTimeModel"
            example:
              startDate: '2025-06-23'
              endDate: '2025-06-27'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/UserNonWorkingTimeModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '401':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                message: You need to be authenticated to access this resource.
          description: Returned if the client is not authenticated.
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** `manage_working_times` globally (for other users) or
            `manage_own_working_times` globally (for own records).
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the user or non-working time record does not exist,
            or if the requesting user does not have permission to view it.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: Validation failed.
          description: |-
            Returned if the request body contains invalid parameters, or if the date range
            overlaps with an existing non-working time record for the user.
    delete:
      summary: Delete a personal non-working time record
      operationId: delete_user_non_working_time
      tags:
      - User Working Times
      description: |-
        Removes the personal non-working time record for the given user.

        **Required permissions:**
        - Administrators can delete non-working time records for any user.
        - Users with the global `manage_own_working_times` permission can delete their own records.
        - Users with the global `manage_working_times` permission can delete non-working time records for any user.

        Use `me` as the `id` to reference the current user.
      parameters:
      - name: id
        in: path
        required: true
        description: User id. Use `me` to reference the current user.
        schema:
          type: string
        example: '42'
      - name: non_working_time_id
        in: path
        required: true
        description: The id of the personal non-working time record.
        schema:
          type: integer
        example: 7
      responses:
        '204':
          description: |-
            No Content.
            The record was deleted successfully.
        '401':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                message: You need to be authenticated to access this resource.
          description: Returned if the client is not authenticated.
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** `manage_working_times` globally (for other users) or
            `manage_own_working_times` globally (for own records).
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the user or non-working time record does not exist,
            or if the requesting user does not have permission to view it.
  "/api/v3/users/{id}/working_hours":
    get:
      summary: List working hours for a user
      operationId: list_user_working_hours
      tags:
      - User Working Times
      description: |-
        Returns all working hours records for the given user, ordered by `validFrom` descending.

        Multiple records may exist for a user; each represents a period of their working time
        configuration. The most recently effective record (the one with the latest `validFrom`
        that is not in the future) is used for capacity calculations.

        **Required permissions:**
        - Administrators can view working hours for any user.
        - Users with the global `manage_working_times` permission can view working hours for any user.
        - Any user can view their own working hours records.

        Use `me` as the `id` to reference the current user.
      parameters:
      - name: id
        in: path
        required: true
        description: User id. Use `me` to reference the current user.
        schema:
          type: string
        example: '42'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/UserWorkingHoursCollectionModel"
        '401':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                message: You need to be authenticated to access this resource.
          description: Returned if the client is not authenticated.
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified user does not exist or you do not have permission
                  to view them.
          description: Returned if the user does not exist or is not visible to the
            requesting user.
    post:
      summary: Create a working hours record for a user
      operationId: create_user_working_hours
      tags:
      - User Working Times
      description: |-
        Creates a new working hours record for the given user, effective from the given date.

        **Required permissions:**
        - Administrators can create working hours records for any user.
        - Users with the global `manage_own_working_times` permission can create records for themselves.
        - Users with the global `manage_working_times` permission can create working hours records for any user.

        Use `me` as the `id` to reference the current user.
      parameters:
      - name: id
        in: path
        required: true
        description: User id. Use `me` to reference the current user.
        schema:
          type: string
        example: '42'
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UserWorkingHoursModel"
            example:
              validFrom: '2025-01-01'
              mondayHours: 8
              tuesdayHours: 8
              wednesdayHours: 8
              thursdayHours: 8
              fridayHours: 8
              saturdayHours: 0
              sundayHours: 0
              availabilityFactor: 100
      responses:
        '201':
          description: Created
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/UserWorkingHoursModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '401':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                message: You need to be authenticated to access this resource.
          description: Returned if the client is not authenticated.
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** `manage_working_times` globally (for other users) or
            `manage_own_working_times` globally (for own records).
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified user does not exist or you do not have permission
                  to view them.
          description: Returned if the user does not exist or is not visible to the
            requesting user.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: Validation failed.
          description: Returned if the request body contains invalid parameters.
  "/api/v3/users/{id}/working_hours/{working_hours_id}":
    get:
      summary: View a working hours record
      operationId: view_user_working_hours_record
      tags:
      - User Working Times
      description: |-
        Returns a single working hours record for the given user.

        **Required permissions:**
        - Administrators can view working hours records for any user.
        - Users with the global `manage_working_times` permission can view working hours for any user.
        - Any user can view their own working hours records.
      parameters:
      - name: id
        in: path
        required: true
        description: User id.
        schema:
          type: integer
        example: 42
      - name: working_hours_id
        in: path
        required: true
        description: Working hours record id.
        schema:
          type: integer
        example: 1
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/UserWorkingHoursModel"
        '401':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                message: You need to be authenticated to access this resource.
          description: Returned if the client is not authenticated.
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the user or working hours record does not exist,
            or if the requesting user does not have permission to view it.
    patch:
      summary: Update a working hours record
      operationId: update_user_working_hours_record
      tags:
      - User Working Times
      description: |-
        Updates the given working hours record.

        Only records that have not yet taken effect (i.e., `validFrom` is in the future) can be
        updated. Attempting to update a record that is already in effect will return a `422` error.

        **Required permissions:**
        - Administrators can update working hours records for any user.
        - Users with the global `manage_own_working_times` permission can update their own records.
        - Users with the global `manage_working_times` permission can update working hours for any user.
      parameters:
      - name: id
        in: path
        required: true
        description: User id.
        schema:
          type: integer
        example: 42
      - name: working_hours_id
        in: path
        required: true
        description: Working hours record id.
        schema:
          type: integer
        example: 2
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UserWorkingHoursModel"
            example:
              mondayHours: 6
              tuesdayHours: 6
              wednesdayHours: 6
              thursdayHours: 6
              fridayHours: 6
              saturdayHours: 0
              sundayHours: 0
              availabilityFactor: 80
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/UserWorkingHoursModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '401':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                message: You need to be authenticated to access this resource.
          description: Returned if the client is not authenticated.
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** `manage_working_times` globally (for other users) or
            `manage_own_working_times` globally (for own records).
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the user or working hours record does not exist,
            or if the requesting user does not have permission to view it.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: Validation failed.
          description: |-
            Returned if the request body contains invalid parameters, or if the record has
            already taken effect and cannot be modified.
    delete:
      summary: Delete a working hours record
      operationId: delete_user_working_hours_record
      tags:
      - User Working Times
      description: |-
        Deletes the given working hours record.

        **Required permissions:**
        - Administrators can delete working hours records for any user.
        - Users with the global `manage_own_working_times` permission can delete their own records.
        - Users with the global `manage_working_times` permission can delete working hours records for any user.
      parameters:
      - name: id
        in: path
        required: true
        description: User id.
        schema:
          type: integer
        example: 42
      - name: working_hours_id
        in: path
        required: true
        description: Working hours record id.
        schema:
          type: integer
        example: 2
      responses:
        '204':
          description: |-
            No Content.
            The record was deleted successfully.
        '401':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                message: You need to be authenticated to access this resource.
          description: Returned if the client is not authenticated.
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** `manage_working_times` globally (for other users) or
            `manage_own_working_times` globally (for own records).
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the user or working hours record does not exist,
            or if the requesting user does not have permission to view it.
  "/api/v3/values/schema/{id}":
    get:
      parameters:
      - name: id
        in: path
        description: |-
          The identifier of the value. This is typically the value of the `property` property of
          the `Values` resource. It should be in lower camelcase format.
        example: startDate
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/SchemaModel"
              examples:
                Values::Property Start date schema:
                  "$ref": "#/components/examples/ValuesPropertyStartDateSchema"
                Values::Property Due date schema:
                  "$ref": "#/components/examples/ValuesPropertyDueDateSchema"
                Values::Property Date schema for Milestone work package:
                  "$ref": "#/components/examples/ValuesPropertyDateSchema"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: Returned if the schema does not exist.
        '400':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:BadRequest
                message: 'Bad request: property is invalid'
          description: Returned if the requested property id is not in a lower camel
            case format.
      tags:
      - Values::Property
      description: The schema of a `Values` resource.
      operationId: View_values_schema
      summary: View Values schema
  "/api/v3/versions":
    get:
      summary: List versions
      operationId: list_versions
      tags:
      - Versions
      description: |-
        Returns a collection of versions. The client can choose to filter the versions similar to how work packages are
        filtered. In addition to the provided filters, the server will reduce the result set to only contain versions,
        for which the requesting client has sufficient permissions (*view_work_packages*).
      parameters:
      - name: filters
        description: |-
          JSON specifying filter conditions. Accepts the same format as returned by
          the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported
          filters are:

          - sharing: filters versions by how they are shared within the server (*none*, *descendants*, *hierarchy*, *tree*, *system*).
          - name: filters versions by their name.
        example: '[{ "sharing": { "operator": "=", "values": ["system"] } }]'
        in: query
        required: false
        schema:
          type: string
      - name: sortBy
        description: |-
          JSON specifying sort criteria. Accepts the same format as returned by
          the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported
          attributes are:

          - id: Sort by the version id
          - name: Sort by the version name using numeric collation, comparing sequences of decimal digits by their numeric value
        example: '[["name", "desc"]]'
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/VersionCollectionModel"
    post:
      summary: Create version
      operationId: create_version
      tags:
      - Versions
      description: |-
        Creates a new version applying the attributes provided in the body. Please note that while there is a fixed set
        of attributes, custom fields can extend a version's attributes and are accepted by the endpoint.

        You can use the form and schema to be retrieve the valid attribute values and by that be guided towards
        successful creation.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/VersionWriteModel"
            examples:
              create version:
                "$ref": "#/components/examples/VersionCreateRequest"
      responses:
        '201':
          description: Created
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/VersionReadModel"
              examples:
                response:
                  "$ref": "#/components/examples/VersionSimpleResponse"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** Manage versions
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
  "/api/v3/versions/available_projects":
    get:
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          categories:
                            href: "/api/v3/projects/6/categories"
                          createWorkPackage:
                            href: "/api/v3/projects/6/work_packages/form"
                            method: post
                          createWorkPackageImmediate:
                            href: "/api/v3/projects/6/work_packages"
                            method: post
                          editWorkPackage:
                            href: "/api/v3//work_packages/{id}/form"
                            method: post
                            templated: true
                          self:
                            href: "/api/v3/projects/6"
                            title: A project
                          versions:
                            href: "/api/v3/projects/6/versions"
                        _type: Project
                        createdAt: '2015-07-06T13:28:14+00:00'
                        description: Eveniet molestias omnis quis aut qui eum adipisci.
                          Atque aut aut in exercitationem adipisci amet. Nisi asperiores
                          quia ratione veritatis enim exercitationem magnam. Aut fuga
                          architecto adipisci nihil. Et repellat pariatur. Aliquam
                          et sed perferendis nostrum quaerat. Fugit doloremque voluptatem.
                        id: 6
                        identifier: a_project
                        name: A project
                        type: Customer Project
                        updatedAt: '2015-10-01T09:55:02+00:00'
                      - _links:
                          categories:
                            href: "/api/v3/projects/14/categories"
                          createWorkPackage:
                            href: "/api/v3/projects/14/work_packages/form"
                            method: post
                          createWorkPackageImmediate:
                            href: "/api/v3/projects/14/work_packages"
                            method: post
                          self:
                            href: "/api/v3/projects/14"
                            title: Another project
                          versions:
                            href: "/api/v3/projects/14/versions"
                        _type: Project
                        createdAt: '2016-02-29T12:50:20+00:00'
                        description: ''
                        id: 14
                        identifier: another_project
                        name: Another project
                        type:
                        updatedAt: '2016-02-29T12:50:20+00:00'
                    _links:
                      self:
                        href: "/api/v3/versions/available_projects"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/Available_projects_for_versionsModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage versions
          headers: {}
      tags:
      - Versions
      description: Gets a list of projects in which a version can be created in. The
        list contains all projects in which the user issuing the request has the manage
        versions permissions.
      operationId: Available_projects_for_versions
      summary: Available projects for versions
  "/api/v3/versions/form":
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/VersionWriteModel"
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/VersionFormModel"
          description: OK
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage versions in any project
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
      tags:
      - Versions
      description: ''
      operationId: Version_create_form
      summary: Version create form
  "/api/v3/versions/schema":
    get:
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _dependencies: []
                    _links:
                      self:
                        href: "/api/v3/versions/schema"
                    _type: Schema
                    createdAt:
                      hasDefault: false
                      name: Created on
                      required: true
                      type: DateTime
                      writable: false
                    customField14:
                      hasDefault: false
                      name: text CF
                      required: false
                      type: String
                      visibility: default
                      writable: true
                    customField40:
                      _links: {}
                      hasDefault: false
                      location: _links
                      name: List CF
                      required: false
                      type: CustomOption
                      visibility: default
                      writable: true
                    definingProject:
                      _links: {}
                      hasDefault: false
                      name: Project
                      required: true
                      type: Project
                      writable: true
                    description:
                      hasDefault: false
                      name: Description
                      required: false
                      type: Formattable
                      writable: true
                    endDate:
                      hasDefault: false
                      name: Finish date
                      required: false
                      type: Date
                      writable: false
                    id:
                      hasDefault: false
                      name: ID
                      required: true
                      type: Integer
                      writable: false
                    name:
                      hasDefault: false
                      maxLength: 60
                      minLength: 1
                      name: Name
                      required: true
                      type: String
                      writable: true
                    sharing:
                      _links: {}
                      hasDefault: false
                      name: Sharing
                      required: true
                      type: String
                      visibility: default
                      writable: true
                    startDate:
                      hasDefault: false
                      name: Start date
                      required: false
                      type: Date
                      writable: true
                    status:
                      _links: {}
                      hasDefault: false
                      name: Status
                      required: true
                      type: String
                      visibility: default
                      writable: true
                    updatedAt:
                      hasDefault: false
                      name: Updated on
                      required: true
                      type: DateTime
                      writable: false
              schema:
                "$ref": "#/components/schemas/Version_schemaModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions to see the schema.

            **Required permission:** view work packages or manage versions on any project
          headers: {}
      tags:
      - Versions
      description: ''
      operationId: View_version_schema
      summary: View version schema
  "/api/v3/versions/{id}":
    get:
      summary: Get version
      operationId: get_version
      tags:
      - Versions
      description: Retrieves a version defined by its unique identifier.
      parameters:
      - description: Version id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/VersionReadModel"
              examples:
                response:
                  "$ref": "#/components/examples/VersionSimpleResponse"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the version does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view work packages **or** manage versions (any project where the version is available)

            *Note: A client without sufficient permissions shall not be able to test for the existence of
            a version. That's why a 404 is returned here, even if a 403 might be more appropriate.*
    delete:
      summary: Delete version
      operationId: delete_Version
      tags:
      - Versions
      description: Deletes the version. Entities associated to the version will no
        longer be assigned to it.
      parameters:
      - description: Version id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Returned if the version was successfully deleted
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage versions
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the version does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view work packages **or** manage versions (any project where the version is available)

            *Note: A client without sufficient permissions shall not be able to test for the existence of
            a version. That's why a 404 is returned here, even if a 403 might be more appropriate.*
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
    patch:
      summary: Update Version
      operationId: update_Version
      tags:
      - Versions
      description: |-
        Updates the given version by applying the attributes provided in the body. Please note that while there is a fixed
        set of attributes, custom fields can extend a version's attributes and are accepted by the endpoint.
      parameters:
      - description: Version id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/VersionWriteModel"
            examples:
              update name:
                "$ref": "#/components/examples/VersionUpdateNameRequest"
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/VersionReadModel"
              examples:
                response:
                  "$ref": "#/components/examples/VersionSimpleResponse"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** Manage versions in the version's project.
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the version does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view work packages **or** manage versions (any project where the version is available)

            *Note: A client without sufficient permissions shall not be able to test for the existence of
            a version. That's why a 404 is returned here, even if a 403 might be more appropriate.*
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if:

            * a constraint for a property was violated (`PropertyConstraintViolation`)
  "/api/v3/versions/{id}/form":
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/VersionWriteModel"
      parameters:
      - description: Project id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/VersionFormModel"
          description: OK
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage versions in the version's project
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
      tags:
      - Versions
      description: ''
      operationId: Version_update_form
      summary: Version update form
  "/api/v3/versions/{id}/projects":
    get:
      parameters:
      - description: Version id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          categories:
                            href: "/api/v3/projects/1/categories"
                          self:
                            href: "/api/v3/projects/1"
                            title: Lorem
                          status:
                            href: "/api/v3/project_statuses/on_track"
                            title: On track
                          versions:
                            href: "/api/v3/projects/1/versions"
                        _type: Project
                        active: true
                        createdAt: '2014-05-21T08:51:20.396Z'
                        description:
                          format: markdown
                          html: "<p>Lorem <strong>ipsum</strong> dolor sit amet</p>"
                          raw: Lorem **ipsum** dolor sit amet
                        id: 1
                        identifier: project_identifier
                        name: Project example
                        statusExplanation:
                          format: markdown
                          html: "<p>Everything <strong>fine</strong></p>"
                          raw: Everything **fine**
                        updatedAt: '2014-05-21T08:51:20.396Z'
                    _links:
                      self:
                        href: "/api/v3/versions/2/projects"
                    _type: Collection
                    count: 1
                    total: 1
              schema:
                "$ref": "#/components/schemas/List_workspaces_by_versionModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if the version does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view work packages **or** manage versions (any project where the given version is available)

            *Note: A client without sufficient permissions shall not be able to test for the existence of a version.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
      tags:
      - Projects
      description: |-
        This endpoint lists the projects where the given version is available.

        The projects returned depend on the sharing settings of the given version,
        but are also limited to the projects that the current user is allowed to see.

        This endpoint is deprecated and replaced by [`/api/v3/versions/{id}/workspaces`](https://www.openproject.org/docs/api/endpoints/projects/#list-workspaces-having-version)
      operationId: List_projects_with_version
      summary: List projects having version
  "/api/v3/versions/{id}/workspaces":
    get:
      parameters:
      - description: Version id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          categories:
                            href: "/api/v3/projects/1/categories"
                          self:
                            href: "/api/v3/projects/1"
                            title: Lorem
                          status:
                            href: "/api/v3/project_statuses/on_track"
                            title: On track
                          versions:
                            href: "/api/v3/projects/1/versions"
                        _type: Project
                        active: true
                        createdAt: '2014-05-21T08:51:20.396Z'
                        description:
                          format: markdown
                          html: "<p>Lorem <strong>ipsum</strong> dolor sit amet</p>"
                          raw: Lorem **ipsum** dolor sit amet
                        id: 1
                        identifier: project_identifier
                        name: Project example
                        statusExplanation:
                          format: markdown
                          html: "<p>Everything <strong>fine</strong></p>"
                          raw: Everything **fine**
                        updatedAt: '2014-05-21T08:51:20.396Z'
                    _links:
                      self:
                        href: "/api/v3/versions/2/projects"
                    _type: Collection
                    count: 1
                    total: 1
              schema:
                "$ref": "#/components/schemas/List_workspaces_by_versionModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if the version does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view work packages **or** manage versions (any workspace where the given version is available)

            *Note: A client without sufficient permissions shall not be able to test for the existence of a version.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
      tags:
      - Projects
      description: |-
        This endpoint lists the workspaces where the given version is available.

        The workspaces returned depend on the sharing settings of the given version,
        but are also limited to the workspaces that the current user is allowed to see.
      operationId: List_workspaces_with_version
      summary: List workspaces having version
  "/api/v3/views":
    get:
      parameters:
      - description: |-
          JSON specifying filter conditions.
          Currently supported filters are:

          + project: filters views by the project their associated query is assigned to. If the project filter is passed with the `!*` (not any) operator, global views are returned.

          + id: filters views based on their id

          + type: filters views based on their type
        example: '[{ "project_id": { "operator": "!*", "values": null } }]'
        in: query
        name: filters
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ViewCollectionModel"
              examples:
                Queries:
                  "$ref": "#/components/examples/Views"
          description: OK
          headers: {}
      tags:
      - Views
      description: Returns a collection of Views. The collection can be filtered via
        query parameters similar to how work packages are filtered.
      operationId: List_views
      summary: List views
  "/api/v3/views/{id}":
    get:
      parameters:
      - description: View id
        example: 42
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ViewModel"
              examples:
                ViewWorkPackagesTable:
                  "$ref": "#/components/examples/ViewWorkPackagesTable"
                ViewTeamPlanner:
                  "$ref": "#/components/examples/ViewTeamPlanner"
          description: Returns the result of a single view, dependent of the view
            type.
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** The required permission depends on the type of the view.
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the resource can not be found.

            *Note: A client without sufficient permissions shall not be able to test for the existence of
            a view. That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
      tags:
      - Views
      description: ''
      operationId: View_view
      summary: View view
    post:
      parameters:
      - description: The view identifier
        name: id
        in: path
        required: true
        example: 1
        schema:
          type: string
      requestBody:
        content:
          application/json:
            examples:
              Views::WorkPackagesTable:
                value:
                  _links:
                    query:
                      href: "/api/v3/queries/5"
              Views::TeamPlanner:
                value:
                  _links:
                    query:
                      href: "/api/v3/queries/5"
            schema:
              type: object
              properties:
                _links:
                  type: object
                  properties:
                    query:
                      type: object
                      properties:
                        href:
                          type: string
                          format: uri
      responses:
        '201':
          content:
            application/hal+json:
              schema:
                type: object
              examples:
                Views::WorkPackagesTable:
                  "$ref": "#/components/examples/ViewWorkPackagesTable"
                Views::TeamPlanner:
                  "$ref": "#/components/examples/ViewTeamPlanner"
          description: Created
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _embedded:
                      details:
                        attribute: query
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Query does not exist.
          description: |-
            Returned if:

            * the client tries to modify a read-only property (`PropertyIsReadOnly`)

            * a constraint for a property was violated (`PropertyConstraintViolation`)

            * the client provides a link to an invalid resource (`ResourceTypeMismatch`),
              e.g. a query not found
          headers: {}
      tags:
      - Views
      description: |-
        When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body.
        The required fields of a View can be found in its schema, which is embedded in the respective form.
        Note that it is only allowed to provide properties or links supporting the write operation.

        There are different subtypes of `Views` (e.g. `Views::WorkPackagesTable`) with each having its own
        endpoint for creating that subtype e.g.

        * `/api/v3/views/work_packages_table` for `Views::WorkPackagesTable`
        * `/api/v3/views/team_planner` for `Views::TeamPlanner`
        * `/api/v3/views/work_packages_calendar` for `Views::WorkPackagesCalendar`

        **Not yet implemented** To get the list of available subtypes and by that the endpoints for creating a subtype, use the
        ```
          /api/v3/views/schemas
        ```
        endpoint.
      operationId: Create_views
      summary: Create view
  "/api/v3/wiki_pages/{id}":
    get:
      parameters:
      - description: Wiki page identifier
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      project:
                        _type: Project...
                        id: 12
                    _links:
                      addAttachment:
                        href: "/api/v3/wiki_pages/72/attachments"
                        method: post
                      attachments:
                        href: "/api/v3/wiki_pages/72/attachments"
                      project:
                        href: "/api/v3/projects/12"
                        title: some project
                      self:
                        href: "/api/v3/wiki_pages/72"
                    _type: WikiPage
                    id: 72
                    title: A wiki page with a name
              schema:
                "$ref": "#/components/schemas/Wiki_PageModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the wiki page does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view wiki page in the page's project
          headers: {}
      tags:
      - Wiki Pages
      description: Retrieve an individual wiki page as identified by the id parameter
      operationId: View_Wiki_Page
      summary: View Wiki Page
  "/api/v3/wiki_pages/{id}/attachments":
    get:
      parameters:
      - description: ID of the wiki page whose attachments will be listed
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          author:
                            href: "/api/v3/users/1"
                            title: OpenProject Admin
                          container:
                            href: "/api/v3/wiki_pages/72"
                            title: wiki
                          delete:
                            href: "/api/v3/attachments/376"
                            method: delete
                          downloadLocation:
                            href: "/api/v3/attachments/376/content"
                          self:
                            href: "/api/v3/attachments/376"
                            title: 200.gif
                        _type: Attachment
                        contentType: image/gif
                        createdAt: '2018-06-01T07:24:19.896Z'
                        description:
                          format: plain
                          html: ''
                          raw: ''
                        digest:
                          algorithm: md5
                          hash: 7ac9c97ef73d47127f590788b84c0c1c
                        fileName: some.gif
                        fileSize: 3521772
                        id: 376
                    _links:
                      self:
                        href: "/api/v3/wiki_pages/72/attachments"
                    _type: Collection
                    count: 1
                    total: 1
              schema:
                "$ref": "#/components/schemas/Attachments_Model"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the wiki page does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view wiki pages

            *Note: A client without sufficient permissions shall not be able to test for the existence of a work package.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
      tags:
      - Attachments
      description: ''
      operationId: List_attachments_by_wiki_page
      summary: List attachments by wiki page
    post:
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              "$ref": "#/components/schemas/FileUploadForm"
            encoding:
              metadata:
                contentType: application/json
              file:
                contentType: "*/*"
      parameters:
      - description: ID of the wiki page to receive the attachment
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '201':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/AttachmentModel"
              examples:
                response:
                  value:
                    _embedded:
                      author:
                        _links:
                          lock:
                            href: "/api/v3/users/1/lock"
                            method: post
                            title: Set lock on admin
                          self:
                            href: "/api/v3/users/1"
                            title: OpenProject Admin
                          showUser:
                            href: "/users/1"
                            type: text/html
                          updateImmediately:
                            href: "/api/v3/users/1"
                            method: patch
                            title: Update admin
                        _type: User
                        admin: true
                        avatar: ''
                        createdAt: '2015-03-20T12:56:52.343Z'
                        email:
                        firstName: OpenProject
                        id: 1
                        identityUrl:
                        lastName: Admin
                        login: admin
                        name: OpenProject Admin
                        status: active
                        updatedAt: '2018-05-29T13:57:44.662Z'
                      container:
                        _links:
                          addAttachment:
                            href: "/api/v3/wiki_pages/72/attachments"
                            method: post
                          attachments:
                            href: "/api/v3/wiki_pages/72/attachments"
                          project:
                            href: "/api/v3/projects/12"
                            title: Demo project
                          self:
                            href: "/api/v3/wiki_pages/72"
                        _type: WikiPage
                        id: 72
                        title: wiki
                    _links:
                      author:
                        href: "/api/v3/users/1"
                        title: OpenProject Admin
                      container:
                        href: "/api/v3/wiki_pages/72"
                        title: wiki
                      delete:
                        href: "/api/v3/attachments/376"
                        method: delete
                      downloadLocation:
                        href: "/api/v3/attachments/376/content"
                      self:
                        href: "/api/v3/attachments/376"
                        title: 200.gif
                    _type: Attachment
                    status: uploaded
                    contentType: image/gif
                    createdAt: '2018-06-01T07:24:19.896Z'
                    description:
                      format: plain
                      html: ''
                      raw: ''
                    digest:
                      algorithm: md5
                      hash: 7ac9c97ef73d47127f590788b84c0c1c
                    fileName: some.gif
                    fileSize: 3521772
                    id: 376
          description: Created
          headers: {}
        '400':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
                    message: The request could not be parsed as JSON.
          description: Returned if the `metadata` part contains unparsable JSON.
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to delete this attachment.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit wiki pages

            *Note that you will only receive this error, if you are at least allowed to see the wiki page*
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the wiki page does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view wiki pages

            *Note: A client without sufficient permissions shall not be able to test for the existence of a wiki page
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: File is too large (maximum size is 5242880 Bytes).
          description: |-
            Returned if the client tries to send an invalid attachment.
            Reasons are:

            * Omitting one of the required parts (`metadata` or `file`)

            * Sending metadata or file parts in an invalid format

            * Omitting the file name (`fileName` property of metadata part)

            * Sending a file that is too large
          headers: {}
      tags:
      - Attachments
      description: Adds an attachment with the wiki page as its container.
      operationId: Add_attachment_to_wiki_page
      summary: Add attachment to wiki page
  "/api/v3/wiki_pages/{id}/attachments/prepare":
    post:
      summary: Prepare a direct attachment upload for a wiki page
      operationId: prepare_wiki_page_attachment_upload
      tags:
      - Attachments
      - Wiki pages
      description: |-
        Prepares a direct upload of an attachment for the given wiki page, to be performed by the
        client without the file content passing through the OpenProject server. See
        `POST /api/v3/attachments/prepare` for a detailed description of the three-step flow this
        endpoint is the first step of.

        Unlike `POST /api/v3/attachments/prepare`, the resulting pending attachment is immediately
        associated with this wiki page as its container.
      parameters:
      - name: id
        description: ID of the wiki page to receive the attachment
        example: 1
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - metadata
              properties:
                metadata:
                  type: string
                  contentMediaType: application/json
                  contentSchema:
                    "$ref": "#/components/schemas/AttachmentPrepareUploadWriteModel"
                  description: |-
                    A **single** part, named `metadata`, whose value is a *JSON-encoded string*
                    conforming to the schema referenced above (see the *Model* tab for its
                    properties) - it must **not** be split into separate `fileName`, `fileSize`, ...
                    form fields. No file content is sent with this request.
                  example: '{"fileName":"cat.png","fileSize":24,"contentType":"image/png"}'
            encoding:
              metadata:
                contentType: application/json
      responses:
        '201':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/AttachmentUploadModel"
        '400':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
                message: The request could not be parsed as JSON.
          description: |-
            Returned if the client sends a not understandable request. Reasons include:

            * Omitting the `metadata` part

            * sending unparsable JSON in the metadata part
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to add attachments to this wiki page.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit wiki pages

            *Note that you will only receive this error, if you are at least allowed to see the wiki page*
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the wiki page does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view wiki pages

            *Note: A client without sufficient permissions shall not be able to test for the existence of a wiki page
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                direct uploads not available:
                  description: Returned if the OpenProject instance is not configured
                    for direct uploads.
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Direct file upload is not available due to a system configuration
                      issue. Please contact your administrator.
                missing file name:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: File can't be blank.
          description: |-
            Returned if the client tries to prepare an invalid attachment upload.
            Reasons are:

            * Omitting the file name (`fileName` property of metadata part)

            * Omitting the file size (`fileSize` property of metadata part)

            * The instance is not configured for direct uploads
  "/api/v3/work_packages":
    get:
      summary: List work packages
      operationId: list_work_packages
      tags:
      - Work Packages
      description: Returns a collection of work packages.
      parameters:
      - description: Page number inside the requested collection.
        example: 25
        in: query
        name: offset
        required: false
        schema:
          default: 1
          type: integer
      - description: Number of elements to display per page.
        example: 25
        in: query
        name: pageSize
        required: false
        schema:
          type: integer
      - description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/)
          endpoint. If no filter is to be applied, the client should send an empty array (`[]`), otherwise a default
          filter is applied. A Currently supported filters are (there are additional filters added by modules):

          - assigned_to
          - assignee_or_group
          - attachment_base
          - attachment_content
          - attachment_file_name
          - author
          - blocked
          - blocks
          - category
          - comment
          - created_at
          - custom_field
          - dates_interval
          - description
          - done_ratio
          - due_date
          - duplicated
          - duplicates
          - duration
          - estimated_hours
          - file_link_origin_id
          - follows
          - group
          - id
          - includes
          - linkable_to_storage_id
          - linkable_to_storage_url
          - manual_sort
          - milestone
          - only_subproject
          - parent
          - partof
          - precedes
          - principal_base
          - priority
          - project
          - relatable
          - relates
          - required
          - requires
          - responsible
          - role
          - search
          - start_date
          - status
          - storage_id
          - storage_url
          - subject
          - subject_or_id
          - subproject
          - type
          - typeahead
          - updated_at
          - version
          - watcher
          - work_package
        example: '[{ "type_id": { "operator": "=", "values": ["1", "2"] }}]'
        in: query
        name: filters
        required: false
        schema:
          default: '[{ "status_id": { "operator": "o", "values": null }}]'
          type: string
      - description: |-
          JSON specifying sort criteria.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint.

          A special `exactMatch` key is available when combined with a `typeahead`
          filter: sorting by `exactMatch` `desc` ranks work packages whose id, sequence number or
          identifier is an exact match for the typeahead search term first,
          regardless of any other sort criteria. Combine it with a secondary
          criterion to break ties, e.g. `[["exactMatch", "desc"], ["updatedAt", "desc"]]`.
        example: '[["status", "asc"]]'
        in: query
        name: sortBy
        required: false
        schema:
          default: '[["id", "asc"]]'
          type: string
      - description: The column to group by.
        example: status
        in: query
        name: groupBy
        required: false
        schema:
          type: string
      - description: Indicates whether properties should be summed up if they support
          it.
        example: true
        in: query
        name: showSums
        required: false
        schema:
          default: false
          type: boolean
      - description: Comma separated list of properties to include.
        example: total,elements/subject,elements/id,self
        in: query
        name: select
        required: false
        schema:
          type: string
      - description: |-
          In order to perform a [baseline comparison](/docs/api/baseline-comparisons), you may provide one or several timestamps
          in ISO-8601 format as comma-separated list. The timestamps may be absolute or relative,
          such as ISO8601 dates, ISO8601 durations and the following relative date keywords: "oneDayAgo@HH:MM+HH:MM",
          "lastWorkingDay@HH:MM+HH:MM", "oneWeekAgo@HH:MM+HH:MM", "oneMonthAgo@HH:MM+HH:MM".
          The first "HH:MM" part represents the zero paded hours and minutes.
          The last "+HH:MM" part represents the timezone offset from UTC associated with the time,
          the offset can be positive or negative e.g."oneDayAgo@01:00+01:00", "oneDayAgo@01:00-01:00".

          Usually, the first timestamp is the baseline date, the last timestamp is the current date.
          Values older than 1 day are accepted only with valid Enterprise Token available.
        example: 2022-01-01T00:00:00Z,PT0S
        in: query
        name: timestamps
        required: false
        schema:
          default: PT0S
          type: string
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/Work_PackagesModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to see work packages.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** view work packages (globally or in any project)
    post:
      summary: Create Work Package
      operationId: create_work_package
      tags:
      - Work Packages
      description: |-
        When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body.
        The required fields of a WorkPackage can be found in its schema, which is embedded in the respective form.
        Note that it is only allowed to provide properties or links supporting the write operation.

        A project link must be set when creating work packages through this route.

        When setting start date, finish date, and duration together, their correctness will be checked and a 422 error will be returned if one value does not match with the two others. You can make the server compute a value: set only two values in the request and the third one will be computed and returned in the response. For instance, when sending `{ "startDate": "2022-08-23", duration: "P2D" }`, the response will include `{ "dueDate": "2022-08-24" }`.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WorkPackageWriteModel"
      parameters:
      - description: |-
          Indicates whether change notifications (e.g. via E-Mail) should be sent.
          Note that this controls notifications for all users interested in changes to the work package (e.g. watchers, author and assignee),
          not just the current user.
        example: false
        in: query
        name: notify
        required: false
        schema:
          default: true
          type: boolean
      responses:
        '201':
          description: Created
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/WorkPackageModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to add work packages to this project.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** add work packages

            *Note that you will only receive this error, if you are at least allowed to see the corresponding project.*
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified project does not exist.
          description: |-
            Returned if the project does not exist or the client does not have sufficient permissions
            to see it.

            **Required permissions:** view project

            *Note: A client without sufficient permissions shall not be able to test for the existence of a project.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: The subject might not be blank.
                _embedded:
                  details:
                    attribute: Subject
          description: |-
            Returned if:

            * the client tries to write a read-only property

            * a constraint for a property was violated

            * a property was provided in an unreadable format
  "/api/v3/work_packages/form":
    post:
      summary: Form for creating a Work Package
      operationId: form_create_work_package
      tags:
      - Work Packages
      description: |-
        When calling this endpoint, the client provides a single object containing the properties and links to be
        created, in the body. The input is validated and a schema response is returned. If the validation errors of the
        response is empty, the same payload can be used to create a work package.

        Only the properties of the work package write model are allowed to set on a work package on creation.

        When setting start date, finish date, and duration together, their correctness will be checked and a validation
        error will be returned if one value does not match with the two others. You can make the server compute a value:
        set only two values in the request and the third one will be computed and returned in the response. For instance,
        when sending `{ "startDate": "2022-08-23", duration: "P2D" }`, the response will
        include `{ "dueDate": "2022-08-24" }`.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WorkPackageWriteModel"
            examples:
              Valid creation:
                "$ref": "#/components/examples/WorkPackageCreateValid"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/WorkPackageFormModel"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
  "/api/v3/work_packages/schemas":
    get:
      summary: List Work Package Schemas
      operationId: list_work_package_schemas
      tags:
      - Work Packages
      description: |-
        List all work package schemas that match the given filters. This endpoint does not return a successful response,
        if no filter is given.
      parameters:
      - name: filters
        description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/)
          endpoint. Currently supported filters are:

          + id: The schema's id

          Schema id has the form `project_id-work_package_type_id`.
        in: query
        required: true
        schema:
          type: string
        example: '[{ "id": { "operator": "=", "values": ["12-1", "14-2"] } }]'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/WorkPackageSchemaCollectionModel"
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          self:
                            href: "/api/v3/work_packages/schemas/13-1"
                        _type: Schema...
                      - _links:
                          self:
                            href: "/api/v3/work_packages/schemas/7-6"
                        _type: Schema...
                    _links:
                      self:
                        href: "/api/v3/work_packages/schemas"
                    _type: Collection
                    count: 2
                    total: 5
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to list schemas.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** View work packages in any project.
          headers: {}
  "/api/v3/work_packages/schemas/{identifier}":
    get:
      parameters:
      - description: Identifier of the schema
        example: 12-13
        in: path
        name: identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/WorkPackageSchemaModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified schema does not exist.
          description: |-
            Returned if the schema does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view work packages (on the project where this schema is used)

            *Note: A client without sufficient permissions shall not be able to test for the existence of a project.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
      tags:
      - Work Packages
      description: ''
      operationId: View_Work_Package_Schema
      summary: View Work Package Schema
  "/api/v3/work_packages/{id}":
    delete:
      summary: Delete Work Package
      operationId: delete_work_package
      tags:
      - Work Packages
      description: |-
        Deletes the work package, as well as:

        - all associated time entries
        - its hierarchy of child work packages
      parameters:
      - description: Work package id
        in: path
        name: id
        required: true
        schema:
          type: integer
        example: 1
      responses:
        '204':
          description: |-
            Returned if the work package was deleted successfully.

            Note that the response body is empty as of now. In future versions of the API a body
            *might* be returned along with an appropriate HTTP status.
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to delete this work package.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** delete work package
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified work package does not exist.
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work package
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
    get:
      summary: View Work Package
      operationId: view_work_package
      tags:
      - Work Packages
      description: Returns the specified work package.
      parameters:
      - description: Work package id
        in: path
        name: id
        required: true
        schema:
          type: integer
        example: 1
      - description: |-
          In order to perform a [baseline comparison](/docs/api/baseline-comparisons) of the work-package attributes, you may
          provide one or several timestamps in ISO-8601 format as comma-separated list. The timestamps may be absolute or relative,
          such as ISO8601 dates, ISO8601 durations and the following relative date keywords: "oneDayAgo@HH:MM+HH:MM",
          "lastWorkingDay@HH:MM+HH:MM", "oneWeekAgo@HH:MM+HH:MM", "oneMonthAgo@HH:MM+HH:MM".
          The first "HH:MM" part represents the zero paded hours and minutes.
          The last "+HH:MM" part represents the timezone offset from UTC associated with the time,
          the offset can be positive or negative e.g."oneDayAgo@01:00+01:00", "oneDayAgo@01:00-01:00".

          Usually, the first timestamp is the baseline date, the last timestamp is the current date.
          Values older than 1 day are accepted only with valid Enterprise Token available.
        in: query
        name: timestamps
        required: false
        schema:
          default: PT0S
          type: string
        example: 2022-01-01T00:00:00Z,PT0S
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/WorkPackageModel"
          description: OK
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified work package does not exist.
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work package
    patch:
      summary: Update a Work Package
      operationId: update_work_package
      tags:
      - Work Packages
      description: "When calling this endpoint the client provides a single object,
        containing the properties and links that it wants\nto change, in the body.
        Note that it is only allowed to provide properties or links supporting the
        **write**\noperation.\n\nAdditionally to the fields the client wants to change,
        it is mandatory to provide the value of `lockVersion` which\nwas received
        by the `GET` request this change originates from.\n\nThe value of `lockVersion`
        is used to implement\n[optimistic locking](https://en.wikipedia.org/wiki/Optimistic_concurrency_control).\n\n**Custom
        Field Validation**  \n\nRequired custom fields are only validated when they
        are explicitly provided in the request body. If a custom field\nis not included
        in the update request, it will not be validated. This enables clients to update\nspecific
        attributes independently without having to provide values for all required
        custom fields.\n\nTo override this behavior and validate all required custom
        fields regardless of whether they are included in the\nrequest, set `validateCustomFields`
        to `true` in the `_meta` object of the request body."
      parameters:
      - name: id
        description: Work package id
        in: path
        required: true
        schema:
          type: integer
        example: 42
      - name: notify
        description: |-
          Indicates whether change notifications should be sent. Note that this controls notifications for all users
          interested in changes to the work package (e.g. watchers, author and assignee), not just the current user.
        in: query
        required: false
        schema:
          type: boolean
          default: true
        example: false
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WorkPackagePatchModel"
            examples:
              With custom field validation:
                "$ref": "#/components/examples/WorkPackageWithMetaValidation"
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/WorkPackageModel"
          description: OK
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to edit the content of the work package.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit work package, assign version, change work package status, manage subtasks or move work package
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified work package does not exist.
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work package
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '409':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:UpdateConflict
                message: Your changes could not be saved, because the work package
                  was changed since you've seen it the last time.
          description: Returned if the resource was changed since the client requested
            it. This is determined using the `lockVersion` property.
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _embedded:
                  details:
                    attribute: Subject
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: The subject might not be blank.
          description: |-
            Returned if:

            - the client tries to modify a read-only property (`PropertyIsReadOnly`)
            - a constraint for a property was violated (`PropertyConstraintViolation`)
            - the client provides a link to an invalid resource (`ResourceTypeMismatch`)
  "/api/v3/work_packages/{id}/activities":
    get:
      parameters:
      - description: Work package id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          self:
                            href: "/api/v3/activity/1"
                          user:
                            href: "/api/v3/users/1"
                          workPackage:
                            href: "/api/v3/work_packages/1"
                        _type: Activity
                        comment:
                          format: markdown
                          html: "<p>Lorem ipsum dolor sit amet.</p>"
                          raw: Lorem ipsum dolor sit amet.
                        createdAt: '2014-05-21T08:51:20.396Z'
                        updatedAt: '2014-05-21T09:14:02.726Z'
                        details: []
                        id: 1
                        version: 1
                      - _links:
                          self:
                            href: "/api/v3/activity/2"
                          user:
                            href: "/api/v3/users/1"
                          workPackage:
                            href: "/api/v3/work_packages/1"
                        _type: Activity
                        comment:
                          format: markdown
                          html: "<p>Lorem ipsum dolor sit amet.</p>"
                          raw: Lorem ipsum dolor sit amet.
                        createdAt: '2014-05-21T09:51:22.077Z'
                        updatedAt: '2014-05-21T10:14:02.957Z'
                        details: []
                        id: 2
                        version: 2
                    _links:
                      self:
                        href: "/api/v3/work_packages/1/revisions"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/Work_Package_activitiesModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified work package does not exist.
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work package
          headers: {}
      tags:
      - Work Packages
      description: ''
      operationId: List_work_package_activities
      summary: List work package activities
    post:
      parameters:
      - description: Work package id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: |-
          Indicates whether change notifications (e.g. via E-Mail) should be sent.
          Note that this controls notifications for all users interested in changes to the work package (e.g. watchers, author and assignee),
          not just the current user.
        example: false
        in: query
        name: notify
        required: false
        schema:
          default: true
          type: boolean
      responses:
        '201':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ActivityModel"
          description: Created
          headers: {}
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to create a comment here.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** create journals

            *Note that you will only receive this error, if you are at least allowed to see the corresponding work package.*
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified work package does not exist.
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work package
          headers: {}
      tags:
      - Work Packages
      description: |-
        Creates an activity for the selected work package and, on success, returns the
        updated activity.
      operationId: Comment_work_package
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ActivityCommentWriteModel"
      summary: Comment work package
  "/api/v3/work_packages/{id}/activities_emoji_reactions":
    get:
      summary: List emoji reactions by work package activities
      operationId: list_work_package_activities_emoji_reactions
      tags:
      - WorkPackages
      - Activities
      - EmojiReactions
      description: List all emoji reactions of all activities of a single work package.
      parameters:
      - name: id
        description: ID of the work package whose activities' emoji reactions will
          be listed
        in: path
        required: true
        schema:
          type: integer
        example: 1
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/EmojiReactions_Model"
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:**
            - `view_work_packages`
            - for internal comments: `view_internal_comments`

            *Note: A client without sufficient permissions shall not be able to test for the existence of a work package.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
  "/api/v3/work_packages/{id}/attachments":
    get:
      parameters:
      - description: ID of the work package whose attachments will be listed
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/Attachments_Model"
          description: OK
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified work package does not exist.
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view work package

            *Note: A client without sufficient permissions shall not be able to test for the existence of a work package.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
      tags:
      - Attachments
      description: ''
      operationId: list_work_package_attachments
      summary: List attachments by work package
    post:
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              "$ref": "#/components/schemas/FileUploadForm"
            encoding:
              metadata:
                contentType: application/json
              file:
                contentType: "*/*"
      parameters:
      - description: ID of the work package to receive the attachment
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '201':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/AttachmentModel"
          description: Created
        '400':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
                message: The request could not be parsed as JSON.
          description: Returned if the `metadata` part contains unparsable JSON.
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to delete this attachment.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit work package or add work package

            *Note that you will only receive this error, if you are at least allowed to see the work package.*
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified work package does not exist.
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view work package

            *Note: A client without sufficient permissions shall not be able to test for the existence of a work package.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: File is too large (maximum size is 5242880 Bytes).
          description: |-
            Returned if the client tries to send an invalid attachment.
            Reasons are:

            * Omitting one of the required parts (`metadata` or `file`)

            * Sending metadata or file parts in an invalid format

            * Omitting the file name (`fileName` property of metadata part)

            * Sending a file that is too large
      tags:
      - Attachments
      description: |-
        To add an attachment to a work package, a client needs to issue a request of type `multipart/form-data`
        with exactly two parts.

        The first part *must* be called `metadata`. Its content type is expected to be `application/json`,
        the body *must* be a single JSON object, containing at least the `fileName` and optionally the attachments `description`.

        The second part *must* be called `file`, its content type *should* match the mime type of the file.
        The body *must* be the raw content of the file.
        Note that a `filename` must be indicated in the `Content-Disposition` of this part, however it will be ignored.
        Instead the `fileName` inside the JSON of the metadata part will be used.
      operationId: create_work_package_attachment
      summary: Create work package attachment
  "/api/v3/work_packages/{id}/attachments/prepare":
    post:
      summary: Prepare a direct attachment upload for a work package
      operationId: prepare_work_package_attachment_upload
      tags:
      - Attachments
      - Work packages
      description: |-
        Prepares a direct upload of an attachment for the given work package, to be performed by the
        client without the file content passing through the OpenProject server. See
        `POST /api/v3/attachments/prepare` for a detailed description of the three-step flow this
        endpoint is the first step of.

        Unlike `POST /api/v3/attachments/prepare`, the resulting pending attachment is immediately
        associated with this work package as its container.
      parameters:
      - name: id
        description: ID of the work package to receive the attachment
        example: 1
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - metadata
              properties:
                metadata:
                  type: string
                  contentMediaType: application/json
                  contentSchema:
                    "$ref": "#/components/schemas/AttachmentPrepareUploadWriteModel"
                  description: |-
                    A **single** part, named `metadata`, whose value is a *JSON-encoded string*
                    conforming to the schema referenced above (see the *Model* tab for its
                    properties) - it must **not** be split into separate `fileName`, `fileSize`, ...
                    form fields. No file content is sent with this request.
                  example: '{"fileName":"cat.png","fileSize":24,"contentType":"image/png"}'
            encoding:
              metadata:
                contentType: application/json
      responses:
        '201':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/AttachmentUploadModel"
        '400':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
                message: The request could not be parsed as JSON.
          description: |-
            Returned if the client sends a not understandable request. Reasons include:

            * Omitting the `metadata` part

            * sending unparsable JSON in the metadata part
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to add attachments to this work package.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit work package or add work package

            *Note that you will only receive this error, if you are at least allowed to see the work package.*
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified work package does not exist.
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view work package

            *Note: A client without sufficient permissions shall not be able to test for the existence of a work package.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                direct uploads not available:
                  description: Returned if the OpenProject instance is not configured
                    for direct uploads.
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Direct file upload is not available due to a system configuration
                      issue. Please contact your administrator.
                missing file name:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: File can't be blank.
          description: |-
            Returned if the client tries to prepare an invalid attachment upload.
            Reasons are:

            * Omitting the file name (`fileName` property of metadata part)

            * Omitting the file size (`fileSize` property of metadata part)

            * The instance is not configured for direct uploads
  "/api/v3/work_packages/{id}/available_assignees":
    get:
      parameters:
      - description: Work package id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          delete:
                            href: "/api/v3/users/1"
                            method: DELETE
                            title: Delete j.sheppard
                          lock:
                            href: "/api/v3/users/1/lock"
                            method: POST
                            title: Set lock on j.sheppard
                          self:
                            href: "/api/v3/users/1"
                            title: John Sheppard - j.sheppard
                        _type: User
                        avatar: https://example.org/users/1/avatar
                        createdAt: '2014-05-21T08:51:20.396Z'
                        email: shep@mail.com
                        firstName: John
                        id: 1
                        lastName: Sheppard
                        login: j.sheppard
                        status: active
                        updatedAt: '2014-05-21T08:51:20.396Z'
                      - _links:
                          delete:
                            href: "/api/v3/users/2"
                            method: DELETE
                            title: Delete j.sheppard2
                          lock:
                            href: "/api/v3/users/2/lock"
                            method: POST
                            title: Set lock on j.sheppard2
                          self:
                            href: "/api/v3/users/2"
                            title: Jim Sheppard - j.sheppard2
                        _type: User
                        avatar: https://example.org/users/1/avatar
                        createdAt: '2014-05-21T08:51:20.396Z'
                        email: shep@mail.net
                        firstName: Jim
                        id: 2
                        lastName: Sheppard
                        login: j.sheppard2
                        status: active
                        updatedAt: '2014-05-21T08:51:20.396Z'
                    _links:
                      self:
                        href: "/api/v3/work_packages/42/available_assignees"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/Available_AssigneesModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to see the assignable users for this
                      work package.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit work packages

            *Note that you will only receive this error, if you are at least allowed to see the corresponding work package.*
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The work package you are looking for cannot be found
                      or has been deleted.
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work packages
          headers: {}
      tags:
      - Work Packages
      description: Gets a list of users that can be assigned to the given work package.
      operationId: Work_Package_Available_assignees
      summary: Work Package Available assignees
  "/api/v3/work_packages/{id}/available_projects":
    get:
      parameters:
      - description: work package id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          categories:
                            href: "/api/v3/projects/6/categories"
                          createWorkPackage:
                            href: "/api/v3/projects/6/work_packages/form"
                            method: post
                          createWorkPackageImmediate:
                            href: "/api/v3/projects/6/work_packages"
                            method: post
                          editWorkPackage:
                            href: "/api/v3//work_packages/{id}/form"
                            method: post
                            templated: true
                          self:
                            href: "/api/v3/projects/6"
                            title: A project
                          versions:
                            href: "/api/v3/projects/6/versions"
                        _type: Project
                        createdAt: '2015-07-06T13:28:14+00:00'
                        description: Eveniet molestias omnis quis aut qui eum adipisci.
                          Atque aut aut in exercitationem adipisci amet. Nisi asperiores
                          quia ratione veritatis enim exercitationem magnam. Aut fuga
                          architecto adipisci nihil. Et repellat pariatur. Aliquam
                          et sed perferendis nostrum quaerat. Fugit doloremque voluptatem.
                        id: 6
                        identifier: a_project
                        name: A project
                        type: Customer Project
                        updatedAt: '2015-10-01T09:55:02+00:00'
                      - _links:
                          categories:
                            href: "/api/v3/projects/14/categories"
                          createWorkPackage:
                            href: "/api/v3/projects/14/work_packages/form"
                            method: post
                          createWorkPackageImmediate:
                            href: "/api/v3/projects/14/work_packages"
                            method: post
                          self:
                            href: "/api/v3/projects/14"
                            title: Another project
                          versions:
                            href: "/api/v3/projects/14/versions"
                        _type: Project
                        createdAt: '2016-02-29T12:50:20+00:00'
                        description: ''
                        id: 14
                        identifier: another_project
                        name: Another project
                        type:
                        updatedAt: '2016-02-29T12:50:20+00:00'
                    _links:
                      self:
                        href: "/api/v3/work_packages/5/available_projects"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/Available_projects_for_work_packageModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** edit work package

            *Note that you will only receive this error, if you are at least allowed to see the corresponding work package.*
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified work package does not exist.
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work package
          headers: {}
      tags:
      - Work Packages
      description: Gets a list of projects that are available as projects to which
        the work package can be moved.
      operationId: Available_projects_for_work_package
      summary: Available projects for work package
  "/api/v3/work_packages/{id}/available_relation_candidates":
    get:
      summary: Available relation candidates
      operationId: list_available_relation_candidates
      tags:
      - Work Packages
      description: ''
      parameters:
      - description: Project id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: Maximum number of candidates to list (default 10)
        example: 25
        in: query
        name: pageSize
        required: false
        schema:
          type: integer
      - description: |-
          JSON specifying filter conditions.
          Accepts the same filters as the [work packages](https://www.openproject.org/docs/api/endpoints/work-packages/) endpoint.
        example: '[{ "status_id": { "operator": "o", "values": null } }]'
        in: query
        name: filters
        required: false
        schema:
          type: string
      - description: Shortcut for filtering by ID or subject
        example: '"rollout"'
        in: query
        name: query
        required: false
        schema:
          type: string
      - description: Type of relation to find candidates for (default "relates")
        example: '"follows"'
        in: query
        name: type
        required: false
        schema:
          type: string
      - description: |-
          JSON specifying sort criteria.
          Accepts the same sort criteria as the [work packages](https://www.openproject.org/docs/api/endpoints/work-packages/) endpoint,
          including the special `exactMatch` key for ranking an exact id/identifier/sequence number match
          for `query` first, e.g. `[["exactMatch", "desc"], ["updatedAt", "desc"]]`.
        example: '[["status", "asc"]]'
        in: query
        name: sortBy
        required: false
        schema:
          default: '[["id", "asc"]]'
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          self:
                            href: "/api/v3/work_packages/1"
                        _type: WorkPackage
                        id: 1
                        subject: Skipped other properties for brevity
                      - _links:
                          self:
                            href: "/api/v3/work_packages/2"
                        _type: WorkPackage
                        id: 2
                        subject: Skipped other properties for brevity
                    _links:
                      self:
                        href: "/api/v3/projects/14/work_packages"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/Available_relation_candidatesModel"
          description: OK
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified work package does not exist.
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work package
  "/api/v3/work_packages/{id}/available_watchers":
    get:
      parameters:
      - description: work package id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          delete:
                            href: "/api/v3/users/1"
                            method: DELETE
                            title: Delete j.sheppard
                          lock:
                            href: "/api/v3/users/1/lock"
                            method: POST
                            title: Set lock on j.sheppard
                          self:
                            href: "/api/v3/users/1"
                            title: John Sheppard - j.sheppard
                        _type: User
                        avatar: https://example.org/users/1/avatar
                        createdAt: '2014-05-21T08:51:20.396Z'
                        email: shep@mail.com
                        firstName: John
                        id: 1
                        lastName: Sheppard
                        login: j.sheppard
                        status: active
                        updatedAt: '2014-05-21T08:51:20.396Z'
                      - _links:
                          delete:
                            href: "/api/v3/users/2"
                            method: DELETE
                            title: Delete j.sheppard2
                          lock:
                            href: "/api/v3/users/2/lock"
                            method: POST
                            title: Set lock on j.sheppard2
                          self:
                            href: "/api/v3/users/2"
                            title: Jim Sheppard - j.sheppard2
                        _type: User
                        avatar: https://example.org/users/1/avatar
                        createdAt: '2014-05-21T08:51:20.396Z'
                        email: shep@mail.net
                        firstName: Jim
                        id: 2
                        lastName: Sheppard
                        login: j.sheppard2
                        status: active
                        updatedAt: '2014-05-21T08:51:20.396Z'
                    _links:
                      self:
                        href: "/api/v3/work_packages/1/available_watchers"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/Available_WatchersModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** add work package watchers

            *Note that you will only receive this error, if you are at least allowed to see the corresponding work package.*
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified work package does not exist.
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work package
          headers: {}
      tags:
      - Work Packages
      description: Gets a list of users that are able to be watchers of the specified
        work package.
      operationId: Available_watchers
      summary: Available watchers
  "/api/v3/work_packages/{id}/file_links":
    post:
      summary: Creates file links.
      operationId: create_work_package_file_link
      tags:
      - Work Packages
      - File links
      description: |-
        Creates file links on a work package.

        The request is interpreted as a bulk insert, where every element of the collection is validated separately. Each
        element contains the origin meta data and a link to the storage, the file link is about to point to. The storage
        link can be provided as a resource link with id or as the host url.

        The file's id and name are considered mandatory information. The rest of the origin meta data SHOULD be provided
        by the client. The _mimeType_ SHOULD be a standard mime type. An empty mime type will be handled as unknown. To link
        a folder, the custom mime type `application/x-op-directory` MUST be used.

        Up to 20 file links can be submitted at once.

        If any element data is invalid, no file links will be created.

        If a file link with matching origin id, work package, and storage already exists, then it will not create an
        additional file link or update the meta data. Instead the information from the existing file link will be returned.
      parameters:
      - name: id
        description: Work package id
        in: path
        required: true
        schema:
          type: integer
        example: 1337
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/FileLinkCollectionWriteModel"
            example:
              _type: Collection
              _embedded:
                elements:
                - originData:
                    id: 5503
                    name: logo.png
                    mimeType: image/png
                    size: 433765
                    createdAt: '2021-12-19T09:42:10.170Z'
                    lastModifiedAt: '2021-12-20T14:00:13.987Z'
                    createdByName: Luke Skywalker
                    lastModifiedByName: Anakin Skywalker
                  _links:
                    storageUrl:
                      href: https://nextcloud.deathstar.rocks/
      responses:
        '201':
          description: Created
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/FileLinkCollectionReadModel"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage file links

            *Note that you will only receive this error, if you are at least allowed to see the corresponding work package.*
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work package, view file links
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: The request was invalid. File Link logo.png - Storage was
                  invalid.
          description: |-
            Occurs if the request body was correctly formatted, but some properties lead to errors in the validation
            process. This happens e.g. if the provided storage url is not available on the server.
    get:
      summary: Gets all file links of a work package
      operationId: list_work_package_file_links
      tags:
      - Work Packages
      - File links
      description: "Gets all file links of a work package.\n\nAs a side effect, for
        every file link a request is sent to the storage's origin to fetch live data
        and patch\nthe file link's data before returning, as well as retrieving permissions
        of the user on this origin file. "
      parameters:
      - name: id
        description: Work package id
        in: path
        required: true
        schema:
          type: integer
        example: 1337
      - name: filters
        in: query
        description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/)
          endpoint. The following filters are supported:

          - storage
        required: false
        example: '[{"storage":{"operator":"=","values":["42"]}}]'
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/FileLinkCollectionReadModel"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** view file links

            *Note that you will only receive this error, if you are at least allowed to see the corresponding work package.*
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work package
  "/api/v3/work_packages/{id}/form":
    post:
      summary: Form for editing a Work Package
      operationId: form_edit_work_package
      tags:
      - Work Packages
      description: "When calling this endpoint, the client provides a single object
        containing the properties and links to be\nedited, in the body. The input
        is validated and a schema response is returned. If the validation errors of
        the\nresponse is empty, the same payload can be used to edit the work package.\n\nOnly
        the properties of the work package write model are allowed to set on a work
        package on editing.\n\nWhen setting start date, finish date, and duration
        together, their correctness will be checked and a validation\nerror will be
        returned if one value does not match with the two others. You can make the
        server compute a value:\nset only two values in the request and the third
        one will be computed and returned in the response. For instance,\nwhen sending
        `{ \"startDate\": \"2022-08-23\", duration: \"P2D\" }`, the response will\ninclude
        `{ \"dueDate\": \"2022-08-24\" }`.\n\n**Custom Field Validation**  \n\nRequired
        custom fields are only validated when they are explicitly provided in the
        request body. If a custom field\nis not included in the form request, it will
        not be validated, allowing clients to validate partial updates\nwithout triggering
        validation errors for unrelated required custom fields.\n\nTo override this
        behavior and validate all required custom fields regardless of whether they
        are included in the\nrequest, set `validateCustomFields` to `true` in the
        `_meta` object of the request body."
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WorkPackageWriteModel"
            examples:
              Changing subject:
                "$ref": "#/components/examples/WorkPackageEditSubject"
              With custom field validation:
                "$ref": "#/components/examples/WorkPackageWithMetaValidation"
      parameters:
      - name: id
        description: ID of the work package being modified
        in: path
        required: true
        schema:
          type: integer
        example: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/WorkPackageFormModel"
        '404':
          description: "Returned if the work package does not exist or the client
            does not have sufficient permissions to see it.\t\n\n**Required permission:**
            view work package"
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified work package does not exist.
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
  "/api/v3/work_packages/{id}/revisions":
    get:
      parameters:
      - description: Work package id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          author:
                            href: "/api/v3/users/1"
                            title: John Sheppard - j.sheppard
                          project:
                            href: "/api/v3/projects/1"
                            title: A Test Project
                          self:
                            href: "/api/v3/revisions/13"
                          showRevision:
                            href: "/projects/identifier/repository/revision/11f4b07"
                        _type: Revision
                        authorName: John Sheppard
                        createdAt: '2015-07-21T13:36:59.220Z'
                        formattedIdentifier: 11f4b07
                        id: 13
                        identifier: 11f4b07dff4f4ce9548a52b7d002daca7cd63ec6
                        message:
                          format: plain
                          html: "<p>This revision provides new features<br/><br/>An
                            elaborate description</p>"
                          raw: |-
                            This revision provides new features

                            An elaborate description
                      - _links:
                          author:
                            href: "/api/v3/users/2"
                            title: Jim Sheppard - j.sheppard
                          project:
                            href: "/api/v3/projects/1"
                            title: A Test Project
                          self:
                            href: "/api/v3/revisions/14"
                          showRevision:
                            href: "/projects/identifier/repository/revision/029ed72a"
                        _type: Revision
                        authorName: j1msheppard
                        createdAt: '2015-06-30T08:47:00.818Z'
                        formattedIdentifier: '029ed72a'
                        id: 13
                        identifier: '029ed72a3b7b7c4ab332b1f6eaa6576e7c946059'
                        message:
                          format: plain
                          html: "<p>This revision fixes some stuff<br/><br/>More information
                            here</p>"
                          raw: |-
                            This revision fixes some stuff

                            More information here
                    _links:
                      self:
                        href: "/api/v3/work_packages/42/revisions"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/RevisionsModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to see linked revisions for this
                      work package.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** view work packages for the project the work package is contained in.

            *Note that you will only receive this error, if you are at least allowed to see the corresponding work package.*
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified work project does not exist.
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work package
          headers: {}
      tags:
      - Work Packages
      description: |-
        Gets a list of revisions that are linked to this work package, e.g., because it is referenced in the commit message of the revision.
        Only linked revisions from repositories are shown if the user has the view changesets permission in the defining project.
      operationId: Revisions
      summary: Revisions
  "/api/v3/work_packages/{id}/relations":
    post:
      summary: Create relation
      operationId: create_relation
      tags:
      - Relations
      description: |-
        Create a work package relation on the given work package. A successful creation will result in a relation between
        two work packages, thus appearing on both involved work package resources.
      parameters:
      - name: id
        description: Work package id
        example: 1
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/RelationWriteModel"
            examples:
              request:
                "$ref": "#/components/examples/RelationCreateRequest"
      responses:
        '201':
          description: Created
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/RelationReadModel"
              examples:
                Simple response:
                  "$ref": "#/components/examples/RelationResponse"
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** manage work package relations
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to create a relation.
        '409':
          description: |-
            Returned if there already exists a relation between the given work packages of **any** type
            or if the relation is not allowed.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:UpdateConflict
                    message: Couldn't update the resource because of conflicting modifications.
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          description: |-
            Returned if:

            - the client tries to write a read-only property (`PropertyIsReadOnly`)
            - a constraint for a property was violated (`PropertyConstraintViolation`)
            - the client provides a link to an invalid resource (`ResourceTypeMismatch`)
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _embedded:
                      details:
                        attribute: lag
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Lag must be a number greater than or equal to 0
  "/api/v3/work_packages/{work_package_id}/reminders":
    get:
      summary: List work package reminders
      operationId: list_work_package_reminders
      tags:
      - Work Packages
      - Reminders
      description: |-
        Gets a list of your upcoming reminders for this work package.

        Only active reminders that belong to the current user are returned.
      parameters:
      - name: work_package_id
        in: path
        description: Work package id
        example: 1
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                type: object
                required:
                - _type
                - total
                - count
                - _embedded
                properties:
                  _type:
                    type: string
                    enum:
                    - Collection
                  total:
                    type: integer
                    description: The total amount of elements available in the collection.
                    minimum: 0
                  count:
                    type: integer
                    description: Actual amount of elements in this response.
                    minimum: 0
                  _embedded:
                    type: object
                    required:
                    - elements
                    properties:
                      elements:
                        type: array
                        items:
                          "$ref": "#/components/schemas/ReminderModel"
        '403':
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** view work packages for the project the work package is contained in.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '404':
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work package
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    post:
      summary: Create a work package reminder
      operationId: create_work_package_reminder
      tags:
      - Work Packages
      - Reminders
      description: |-
        Creates a new reminder for the specified work package.

        **Note:** A user can only have one **active** reminder at a time for a given work package.
      parameters:
      - name: work_package_id
        in: path
        description: Work package id
        example: 1
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - remindAt
              properties:
                remindAt:
                  type: string
                  format: date-time
                  description: The date and time when the reminder is due
                note:
                  type: string
                  description: The note of the reminder
      responses:
        '201':
          description: Reminder created successfully
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ReminderModel"
        '404':
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work package
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '409':
          description: |-
            Returned if the user already has an active reminder for this work package.

            **Error message**: You can only set one reminder at a time for a work package. Please delete or update the existing reminder.
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/work_packages/{id}/watchers":
    get:
      parameters:
      - description: Work package id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              example:
                _embedded:
                  elements:
                  - _links:
                      delete:
                        href: "/api/v3/users/1"
                        method: DELETE
                        title: Delete j.sheppard
                      lock:
                        href: "/api/v3/users/1/lock"
                        method: POST
                        title: Set lock on j.sheppard
                      self:
                        href: "/api/v3/users/1"
                        title: John Sheppard - j.sheppard
                      showUser:
                        href: "/users/1"
                        type: text/html
                    _type: User
                    avatar: https://example.org/users/1/avatar
                    createdAt: '2014-05-21T08:51:20.396Z'
                    firstName: John
                    id: 1
                    lastName: Sheppard
                    login: j.sheppard
                    mail: shep@mail.com
                    status: active
                    updatedAt: '2014-05-21T08:51:20.396Z'
                  - _links:
                      delete:
                        href: "/api/v3/users/2"
                        method: DELETE
                        title: Delete j.sheppard2
                      lock:
                        href: "/api/v3/users/2/lock"
                        method: POST
                        title: Set lock on j.sheppard2
                      self:
                        href: "/api/v3/users/2"
                        title: Jim Sheppard - j.sheppard2
                    _type: User
                    avatar: https://example.org/users/1/avatar
                    createdAt: '2014-05-21T08:51:20.396Z'
                    firstName: Jim
                    id: 2
                    lastName: Sheppard
                    login: j.sheppard2
                    mail: shep@mail.net
                    status: active
                    updatedAt: '2014-05-21T08:51:20.396Z'
                _links:
                  self:
                    href: "/api/v3/work_packages/14/watchers"
                _type: Collection
                count: 2
                total: 2
              schema:
                "$ref": "#/components/schemas/WatchersModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to see the watchers of this work package.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** view work package watchers

            *Note that you will only receive this error, if you are at least allowed to see the corresponding work package.*
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified work package does not exist.
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work package

            *Note that you will effectively not be able to see the watchers of a work package without being able to see the work package.*
          headers: {}
      tags:
      - Work Packages
      description: ''
      operationId: List_watchers
      summary: List watchers
    post:
      parameters:
      - description: Work package id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/UserModel"
          description: OK
          headers: {}
        '201':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/UserModel"
          description: Created
          headers: {}
        '400':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
                message: The request body was not a single JSON object.
          description: |-
            Occurs when the client did not send a valid JSON object in the request body.

            For example:

            * The request did not contain a single JSON object

            * The JSON object did not contain the key `user`

            * The value of `users` was not a link object
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to add watchers to this work package.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permissions:**

            * view work package (for self)

            * add work package watchers (for other users)

            *Note that you will only receive this error, if you are at least allowed to see the corresponding work package.*
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified work package does not exist.
          description: |-
            Returned if the work package does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work package

            *Note that you will effectively not be able to change the watchers of a work package without being able to see the work package.*
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
          description: |-
            Returned if:

            * the client tries to specify a link to a resource that is not a user (`ResourceTypeMismatch`)

            * the user specified is not allowed to watch that work package (`PropertyConstraintViolation`)

            * the user specified does not exist (`PropertyConstraintViolation`)
          headers: {}
      tags:
      - Work Packages
      description: |-
        Adds a watcher to the specified work package.

        The request is expected to contain a single JSON object, that contains a link object under the `user` key.

        The response will be user added as watcher.
        In case the user was already watching the work package an `HTTP 200` is returned, an
        `HTTP 201` if the user was added as a new watcher.
      operationId: Add_watcher
      requestBody:
        content:
          application/json:
            schema:
              example:
                user:
                  href: "/api/v3/users/1"
              properties:
                user:
                  properties:
                    href:
                      type: string
                  type: object
              type: object
      summary: Add watcher
  "/api/v3/work_packages/{id}/watchers/{user_id}":
    delete:
      parameters:
      - description: Work package id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: User id
        example: 1
        in: path
        name: user_id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: No Content
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to remove watchers from this work
                      package.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** delete work package watchers

            *Note that you will only receive this error, if you are at least allowed to see the corresponding work package.*
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified work package does not exist.
          description: |-
            Returned in one of the following cases:

            Either the work package does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view work package

            Or the specified user does not exist at all.

            *Note that you will effectively not be able to change the watchers of a work package without being able to see the work package.*
          headers: {}
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
      tags:
      - Work Packages
      description: |-
        Removes the specified user from the list of watchers for the given work package.

        If the request succeeds, the specified user is not watching the work package anymore.

        *Note: This might also be the case, if the specified user did not watch the work package prior to the request.*
      operationId: Remove_watcher
      summary: Remove watcher
  "/api/v3/workspaces":
    get:
      summary: List workspace
      operationId: list_workspace
      tags:
      - Workspace
      description: |-
        Returns a collection of workspaces. The collection can be filtered via query parameters similar to how work packages are filtered. In addition to the provided filter, the result set is always limited to only contain workspaces the client is allowed to see.
        Since workspaces are the generic term for a number of resources like projects and portfolios, the returned collection will contain a mix of those resources.
      parameters:
      - name: filters
        schema:
          type: string
        in: query
        required: false
        description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint.
          Currently supported filters are:

          + active: based on the active property of the workspace
          + ancestor: filters workspace by their ancestor. A workspace is not considered to be its own ancestor.
          + available_project_attributes: filters workspace based on the activated project attributes.
          + created_at: based on the time the workspace was created
          + favorited: based on the favorited property of the workspace
          + id: based on workspace' id.
          + latest_activity_at: based on the time the last activity was registered on a workspace.
          + name_and_identifier: based on both the name and the identifier.
          + parent_id: filters workspace by their parent.
          + principal: based on members of the workspace.
          + project_phase_any: based on the project phases active in a workspace.
          + project_status_code: based on status code of the workspace
          + storage_id: filters workspace by linked storages
          + storage_url: filters workspace by linked storages identified by the host url
          + type_id: based on the types active in a workspace.
          + user_action: based on the actions the current user has in the workspace.
          + visible: based on the visibility for the user (id) provided as the filter value. This filter is useful for admins to identify the workspace visible to a user.

          There might also be additional filters based on the custom fields that have been configured.

          Each defined lifecycle step will also define a filter in this list endpoint. Given that the elements are not
          static but rather dynamically created on each OpenProject instance, a list cannot be provided. Those filters follow the schema:
          + project_start_gate_[id]: a filter on a project phase's start gate active in a workspace. The id is the id of the phase the gate belongs to.
          + project_finish_gate_[id]: a filter on a project phase's finish gate active in a workspace. The id is the id of the phase the gate belongs to.
          + project_phase_[id]: a filter on a project phase active in a workspace. The id is the id of the phase queried for.
        example: '[{ "ancestor": { "operator": "=", "values": ["1"] } }]'
      - name: sortBy
        schema:
          type: string
        in: query
        required: false
        description: |-
          JSON specifying sort criteria.
          Currently supported orders are:

          + id
          + name
          + typeahead (sorting by hierarchy and name)
          + created_at
          + public
          + latest_activity_at
          + required_disk_space

          There might also be additional orders based on the custom fields that have been configured.
        example: '[["id", "asc"]]'
      - name: select
        schema:
          type: string
        in: query
        required: false
        description: Comma separated list of properties to include.
        example: total,elements/identifier,elements/name
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/WorkspaceCollectionModel"
        '400':
          description: Returned if the client sends invalid request parameters e.g.
            filters
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
                message: Filters Invalid filter does not exist.
  "/api/v3/workspaces/{id}/available_assignees":
    get:
      parameters:
      - description: Workspace id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          delete:
                            href: "/api/v3/users/1"
                            method: DELETE
                            title: Delete j.sheppard
                          lock:
                            href: "/api/v3/users/1/lock"
                            method: POST
                            title: Set lock on j.sheppard
                          self:
                            href: "/api/v3/users/1"
                            title: John Sheppard - j.sheppard
                        _type: User
                        avatar: https://example.org/users/1/avatar
                        createdAt: '2014-05-21T08:51:20.396Z'
                        email: shep@mail.com
                        firstName: John
                        id: 1
                        lastName: Sheppard
                        login: j.sheppard
                        status: active
                        updatedAt: '2014-05-21T08:51:20.396Z'
                      - _links:
                          delete:
                            href: "/api/v3/users/2"
                            method: DELETE
                            title: Delete j.sheppard2
                          lock:
                            href: "/api/v3/users/2/lock"
                            method: POST
                            title: Set lock on j.sheppard2
                          self:
                            href: "/api/v3/users/2"
                            title: Jim Sheppard - j.sheppard2
                        _type: User
                        avatar: https://example.org/users/1/avatar
                        createdAt: '2014-05-21T08:51:20.396Z'
                        email: shep@mail.net
                        firstName: Jim
                        id: 2
                        lastName: Sheppard
                        login: j.sheppard2
                        status: active
                        updatedAt: '2014-05-21T08:51:20.396Z'
                    _links:
                      self:
                        href: "/api/v3/workspaces/42/available_assignees"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/Available_AssigneesModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not allowed to see the assignable users for this
                      workspace.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** add work packages

            *Note that you will only receive this error, if you are at least allowed to see the corresponding workspace.*
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified workspace does not exist.
          description: |-
            Returned if the workspace does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view workspace
          headers: {}
      tags:
      - Work Packages
      description: Gets a list of users that can be assigned to work packages in the
        given workspace.
      operationId: Workspace_Available_assignees
      summary: Workspace Available assignees
  "/api/v3/workspaces/{id}/categories":
    get:
      parameters:
      - description: ID of the workspace whose categories will be listed
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          defaultAssignee:
                            href: "/api/v3/users/42"
                            title: John Sheppard
                          project:
                            href: "/api/v3/projects/11"
                            title: Example project
                          self:
                            href: "/api/v3/categories/10"
                            title: Category with assignee
                        _type: Category
                        id: 10
                        name: Foo
                      - _links:
                          project:
                            href: "/api/v3/projects/11"
                          self:
                            href: "/api/v3/categories/11"
                        _type: Category
                        id: 11
                        name: Bar
                    _links:
                      self:
                        href: "/api/v3/projects/11/categories"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/Categories_by_WorkspaceModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified project does not exist.
          description: |-
            Returned if the workspace does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view workspace

            *Note: A client without sufficient permissions shall not be able to test for the existence of a workspace.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
      tags:
      - Categories
      description: List all categories of a project
      operationId: List_categories_of_a_workspace
      summary: List categories of a workspace
  "/api/v3/workspaces/{id}/favorite":
    delete:
      parameters:
      - description: Workspace id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Returned if the workspace was successfully removed from favorites.
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the workspace does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view workspace
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** logged in
      tags:
      - Workspaces
      - Favorites
      description: Removes the workspace from the current user's favorites.
      operationId: Unfavorite_Workspace
      summary: Unfavorite Workspace
    post:
      parameters:
      - description: Workspace id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Returned if the workspace was successfully added to favorites.
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the workspace does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view workspace
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** logged in
      tags:
      - Workspaces
      - Favorites
      description: Adds the workspace to the current user's favorites.
      operationId: Favorite_Workspace
      summary: Favorite Workspace
  "/api/v3/workspaces/{id}/queries/default":
    get:
      summary: View default query for workspace
      operationId: View_default_query_for_workspace
      tags:
      - Queries
      description: Same as [viewing an existing, persisted Query](https://www.openproject.org/docs/api/endpoints/queries/#list-queries)
        in its response, this resource returns an unpersisted query and by that allows
        to get the default query configuration. The client may also provide additional
        parameters which will modify the default query. The query will already be
        scoped to the workspace.
      parameters:
      - description: Id of the workspace the default query is requested for
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      - name: filters
        description: |-
          JSON specifying filter conditions.
          The filters provided as parameters are not applied to the query but are instead used to override the query's persisted filters.
          All filters also accepted by the work packages endpoint are accepted. If no filter is to be applied, the client should send an empty array (`[]`).
        example: '[{ "assignee": { "operator": "=", "values": ["1", "5"] } }]'
        in: query
        required: false
        schema:
          default: '[{ "status_id": { "operator": "o", "values": null }}]'
          type: string
      - name: offset
        description: Page number inside the queries' result collection of work packages.
        example: 25
        in: query
        required: false
        schema:
          default: 1
          type: integer
      - name: pageSize
        description: Number of elements to display per page for the queries' result
          collection of work packages.
        example: 25
        in: query
        required: false
        schema:
          type: integer
      - name: sortBy
        description: JSON specifying sort criteria. The sort criteria is applied to
          the query's result collection of work packages overriding the query's persisted
          sort criteria.
        example: '[["status", "asc"]]'
        in: query
        required: false
        schema:
          default: '[["id", "asc"]]'
          type: string
      - name: groupBy
        description: The column to group by. The grouping criteria is applied to the
          to the query's result collection of work packages overriding the query's
          persisted group criteria.
        example: status
        in: query
        required: false
        schema:
          type: string
      - name: showSums
        description: Indicates whether properties should be summed up if they support
          it. The showSums parameter is applied to the to the query's result collection
          of work packages overriding the query's persisted sums property.
        example: true
        in: query
        required: false
        schema:
          default: false
          type: boolean
      - name: timestamps
        description: 'Indicates the timestamps to filter by when showing changed attributes
          on work packages. Values can be either ISO8601 dates, ISO8601 durations
          and the following relative date keywords: "oneDayAgo@HH:MM+HH:MM", "lastWorkingDay@HH:MM+HH:MM",
          "oneWeekAgo@HH:MM+HH:MM", "oneMonthAgo@HH:MM+HH:MM". The first "HH:MM" part
          represents the zero paded hours and minutes. The last "+HH:MM" part represents
          the timezone offset from UTC associated with the time. Values older than
          1 day are accepted only with valid Enterprise Token available.

          '
        example: 2023-01-01,P-1Y,PT0S,lastWorkingDay@12:00
        in: query
        required: false
        schema:
          default: PT0S
          type: string
      - name: timelineVisible
        description: Indicates whether the timeline should be shown.
        example: true
        in: query
        required: false
        schema:
          default: false
          type: boolean
      - name: showHierarchies
        description: Indicates whether the hierarchy mode should be enabled.
        example: true
        in: query
        required: false
        schema:
          default: true
          type: boolean
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      results:
                        _embedded:
                          elements:
                          - "<--- shortened for brevity --->"
                        _links:
                          changeSize:
                            href: "/api/v3/workspaces/42/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=%7Bsize%7D&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                            templated: true
                          createWorkPackage:
                            href: "/api/v3/work_packages/form"
                            method: post
                          createWorkPackageImmediate:
                            href: "/api/v3/work_packages"
                            method: post
                          jumpTo:
                            href: "/api/v3/workspaces/42/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=%7Boffset%7D&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                            templated: true
                          self:
                            href: "/api/v3/workspaces/42/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                        _type: WorkPackageCollection
                        count: 30
                        offset: 1
                        pageSize: 2
                        total: 234
                    _links:
                      columns:
                      - href: "/api/v3/queries/columns/id"
                        title: ID
                      - href: "/api/v3/queries/columns/subject"
                        title: Subject
                      - href: "/api/v3/queries/columns/type"
                        title: Type
                      - href: "/api/v3/queries/columns/status"
                        title: Status
                      - href: "/api/v3/queries/columns/priority"
                        title: Priority
                      - href: "/api/v3/queries/columns/assignee"
                        title: Assignee
                      - href: "/api/v3/queries/columns/updated_at"
                        title: Updated on
                      groupBy:
                        href:
                        title:
                      project:
                        href: "/api/v3/projects/42"
                        title: Lorem ipsum project
                      results:
                        href: "/api/v3/workspaces/42/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                      self:
                        href: "/api/v3/workspaces/42/queries/default"
                        title: Default
                      sortBy:
                      - href: "/api/v3/queries/sort_bys/parent-desc"
                        title: Parent (Descending)
                      user:
                        href: "/api/v3/users/1"
                        title: OpenProject Admin
                    _type: Query
                    filters:
                    - _links:
                        filter:
                          href: "/api/v3/queries/filters/status"
                          title: Status
                        operator:
                          href: "/api/v3/queries/operators/o"
                          title: open
                        schema:
                          href: "/api/v3/queries/filter_instance_schemas/status"
                        values: []
                      _type: StatusQueryFilter
                      name: Status
                    name: default
                    public: false
                    showHierarchies: true
                    starred: false
                    sums: false
                    timelineVisible: false
                    timelineZoomLevel: days
              schema:
                "$ref": "#/components/schemas/Default_Query_for_WorkspaceModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions to see the default query.

            **Required permission:** view work packages in the workspace
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: |-
            Returned if the client does not have sufficient permissions to see the workspace.

            **Required permission:** any permission in the workspace
          headers: {}
  "/api/v3/workspace/{id}/queries/filter_instance_schemas":
    get:
      parameters:
      - description: Workspace id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _dependencies:
                        - _type: SchemaDependency
                          dependencies:
                            "/api/v3/queries/operators/!":
                              values:
                                _links: {}
                                hasDefault: false
                                name: Values
                                required: true
                                type: "[]User"
                                writable: true
                            "/api/v3/queries/operators/!*": {}
                            "/api/v3/queries/operators/*": {}
                            "/api/v3/queries/operators/=":
                              values:
                                _links: {}
                                hasDefault: false
                                name: Values
                                required: true
                                type: "[]User"
                                writable: true
                          'on': operator
                        _links:
                          filter:
                            href: "/api/v3/queries/filters/assignee"
                            title: Assignee
                          self:
                            href: "/api/v3/queries/filter_instance_schemas/assignee"
                        _type: QueryFilterInstanceSchema
                        filter:
                          _links: {}
                          hasDefault: false
                          name: Filter
                          required: true
                          type: QueryFilter
                          writable: true
                        name:
                          hasDefault: true
                          name: Name
                          required: true
                          type: String
                          writable: false
                      - _dependencies:
                        - _type: SchemaDependency
                          dependencies:
                            "/api/v3/queries/operators/!":
                              values:
                                _links: {}
                                hasDefault: false
                                name: Values
                                required: true
                                type: "[]User"
                                writable: true
                            "/api/v3/queries/operators/=":
                              values:
                                _links: {}
                                hasDefault: false
                                name: Values
                                required: true
                                type: "[]User"
                                writable: true
                          'on': operator
                        _links:
                          filter:
                            href: "/api/v3/queries/filters/author"
                            title: Author
                          self:
                            href: "/api/v3/queries/filter_instance_schemas/author"
                        _type: QueryFilterInstanceSchema
                        filter:
                          _links: {}
                          hasDefault: false
                          name: Filter
                          required: true
                          type: QueryFilter
                          writable: true
                        name:
                          hasDefault: true
                          name: Name
                          required: true
                          type: String
                          writable: false
                    _links:
                      self:
                        href: "/api/v3/workspaces/42/queries/filter_instance_schemas"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/Query_Filter_Instance_Schemas_For_WorkspaceModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
                    message: You are not authorized to access this resource.
          description: |-
            Returned if the client does not have sufficient permissions to see it.

            **Required permission:** view work package in any workspace
          headers: {}
      tags:
      - Query Filter Instance Schema
      description: Returns the list of QueryFilterInstanceSchemas defined for a query
        of the specified workspace.
      operationId: List_Query_Filter_Instance_Schemas_for_Workspace
      summary: List Query Filter Instance Schemas for Workspace
  "/api/v3/workspace/{id}/queries/schema":
    get:
      parameters:
      - description: Project id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                QuerySchema:
                  "$ref": "#/components/examples/QuerySchemaModel"
              schema:
                "$ref": "#/components/schemas/Schema_For_Workspace_QueriesModel"
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: "**Required permission:** view work package in the workspace"
          headers: {}
      tags:
      - Queries
      description: Retrieve the schema for workspace queries.
      operationId: View_schema_for_workspace_queries
      summary: View schema for workspace queries
  "/api/v3/workspaces/{id}/types":
    get:
      parameters:
      - description: ID of the workspace whose types will be listed
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          self:
                            href: "/api/v3/types/1"
                        _type: Type
                        color: "#ff0000"
                        createdAt: '2014-05-21T08:51:20.396Z'
                        id: 1
                        isDefault: true
                        isMilestone: false
                        name: Bug
                        position: 1
                        updatedAt: '2014-05-21T08:51:20.396Z'
                      - _links:
                          self:
                            href: "/api/v3/types/2"
                        _type: Type
                        color: "#888"
                        createdAt: '2014-05-21T08:51:20.396Z'
                        id: 2
                        isDefault: false
                        isMilestone: false
                        name: Feature
                        position: 2
                        updatedAt: '2014-05-21T08:51:20.396Z'
                    _links:
                      self:
                        href: "/api/v3/workspaces/11/types"
                    _type: Collection
                    count: 2
                    total: 2
              schema:
                "$ref": "#/components/schemas/Types_by_WorkspaceModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified workspace does not exist.
          description: |-
            Returned if the workspace does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view work packages **or** manage types (on given workspace)

            *Note: A client without sufficient permissions shall not be able to test for the existence of a workspace.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
      tags:
      - Types
      - Workspaces
      description: This endpoint lists the types that are *available* in a given workspace.
      operationId: List_types_available_in_a_workspace
      summary: List types available in a workspace
  "/api/v3/workspaces/{id}/work_packages":
    get:
      summary: Get work packages of workspace
      operationId: Get_Workspace_Work_Package_Collection
      tags:
      - Work Packages
      description: Returns the collection of work packages that are related to the
        given workspace.
      parameters:
      - description: Workspace id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: Page number inside the requested collection.
        example: 25
        in: query
        name: offset
        required: false
        schema:
          default: 1
          type: integer
      - description: Number of elements to display per page.
        example: 25
        in: query
        name: pageSize
        required: false
        schema:
          type: integer
      - description: |-
          JSON specifying filter conditions.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. If no filter is to be applied, the client should send an empty array (`[]`).
        example: '[{ "type_id": { "operator": "=", "values": ["1", "2"] }}]'
        in: query
        name: filters
        required: false
        schema:
          default: '[{ "status_id": { "operator": "o", "values": null }}]'
          type: string
      - description: |-
          JSON specifying sort criteria.
          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint.
        example: '[["status", "asc"]]'
        in: query
        name: sortBy
        required: false
        schema:
          default: '[["id", "asc"]]'
          type: string
      - description: The column to group by.
        example: status
        in: query
        name: groupBy
        required: false
        schema:
          type: string
      - description: Indicates whether properties should be summed up if they support
          it.
        example: true
        in: query
        name: showSums
        required: false
        schema:
          default: false
          type: boolean
      - description: Comma separated list of properties to include.
        example: total,elements/subject,elements/id,self
        in: query
        name: select
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/Work_PackagesModel"
          description: OK
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to see the work packages of this project.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** view work packages

            *Note that you will only receive this error, if you are at least allowed to see the corresponding workspace.*
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified project does not exist.
          description: |-
            Returned if the workspace does not exist or the client does not have sufficient permissions to see it.

            **Required permission:** view workspace
    post:
      summary: Create work package in workspace
      operationId: Create_Workspace_Work_Package
      tags:
      - Work Packages
      description: |-
        When calling this endpoint the client provides a single object, containing at least the properties and links that
        are required, in the body. The required fields of a WorkPackage can be found in its schema, which is embedded in
        the respective form. Note that it is only allowed to provide properties or links supporting the write operation.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WorkPackageWriteModel"
      parameters:
      - description: Project id
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: |-
          Indicates whether change notifications (e.g. via E-Mail) should be sent.
          Note that this controls notifications for all users interested in changes to the work package (e.g. watchers, author and assignee),
          not just the current user.
        example: false
        in: query
        name: notify
        required: false
        schema:
          default: true
          type: boolean
      responses:
        '201':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/WorkPackageModel"
          description: Created
        '400':
          "$ref": "#/components/responses/InvalidRequestBody"
        '403':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to add work packages to this workspace.
          description: |-
            Returned if the client does not have sufficient permissions.

            **Required permission:** add work packages

            *Note that you will only receive this error, if you are at least allowed to see the corresponding workspace.*
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified project does not exist.
          description: |-
            Returned if the workspace does not exist or the client does not have sufficient permissions
            to see it.

            **Required permissions:** view workspace

            *Note: A client without sufficient permissions shall not be able to test for the existence of a workspace.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
        '406':
          "$ref": "#/components/responses/MissingContentType"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
        '422':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              example:
                _embedded:
                  details:
                    attribute: Subject
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: The subject might not be blank.
          description: |-
            Returned if:

            * the client tries to write a read-only property

            * a constraint for a property was violated

            * a property was provided in an unreadable format
  "/api/v3/workspaces/{id}/work_packages/form":
    post:
      summary: Form for creating Work Packages in a Workspace
      operationId: form_create_work_package_in_workspace
      tags:
      - Work Packages
      description: |-
        This endpoint allows you to validation a new work package creation body in a specific workspace. It works similarly
        to the `/api/v3/work_packages/form` endpoint, but already specifies the work package's workspace in the path, so that
        it does not have to be defined in the request body.
      parameters:
      - name: id
        description: ID of the workspace in which the work package will be created
        in: path
        required: true
        schema:
          type: integer
        example: 1
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WorkPackageWriteModel"
            examples:
              Minimal example:
                "$ref": "#/components/examples/WorkPackageCreateOnlySubject"
              Valid example:
                "$ref": "#/components/examples/WorkPackageCreateValid"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/WorkPackageFormModel"
        '415':
          "$ref": "#/components/responses/UnsupportedMediaType"
  "/api/v3/workspaces/{id}/versions":
    get:
      parameters:
      - description: ID of the workspace whose versions will be listed
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _embedded:
                      elements:
                      - _links:
                          availableInProjects:
                            href: "/api/v3/versions/11/workspaces"
                          definingProject:
                            href: "/api/v3/projects/11"
                          self:
                            href: "/api/v3/versions/11"
                        _type: Version
                        description:
                          format: plain
                          html: This version has a description
                          raw: This version has a description
                        endDate:
                        id: 11
                        name: v3.0 Alpha
                        startDate: '2014-11-20'
                        status: Open
                      - _links:
                          availableInProjects:
                            href: "/api/v3/versions/12/workspaces"
                          definingProject:
                            href: "/api/v3/projects/11"
                          self:
                            href: "/api/v3/versions/12"
                        _type: Version
                        description:
                          format: plain
                          html: ''
                          raw: ''
                        endDate:
                        id: 12
                        name: v2.0
                        startDate:
                        status: Closed
                      - _links:
                          availableInProjects:
                            href: "/api/v3/versions/10/workspaces"
                          definingProject:
                            href: "/api/v3/projects/11"
                          self:
                            href: "/api/v3/versions/10"
                        _type: Version
                        description:
                          format: plain
                          html: ''
                          raw: ''
                        endDate:
                        id: 10
                        name: v1.0
                        startDate:
                        status: Open
                    _links:
                      self:
                        href: "/api/v3/workspaces/11/versions"
                    _type: Collection
                    count: 3
                    total: 3
              schema:
                "$ref": "#/components/schemas/Versions_by_WorkspaceModel"
          description: OK
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified project does not exist.
          description: |-
            Returned if the workspace does not exist or the client does not have sufficient permissions
            to see it.

            **Required permission:** view work packages **or** manage versions (on given workspace)

            *Note: A client without sufficient permissions shall not be able to test for the existence of a workspace.
            That's why a 404 is returned here, even if a 403 might be more appropriate.*
          headers: {}
      tags:
      - Versions
      description: |-
        This endpoint lists the versions that are *available* in a given workspace.
        Note that due to sharing this might be more than the versions *defined* by that workspace.
      operationId: List_versions_available_in_a_workspace
      summary: List versions available in a workspace
  "/api/v3/workspaces/schema":
    get:
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _