OpenProject Meetings API

openapi: 3.2.0
info:
  description: You're looking at the current **stable** documentation of the OpenProject APIv3.
  title: OpenProject API V3 (Stable) Meetings API
  version: '3'
servers:
- url: https://qa.openproject-edge.com
  description: Edge QA instance
- url: https://qa.openproject-stage.com
  description: Staging instance
- url: https://community.openproject.org
  description: Community instance
security:
- BasicAuth: []
tags:
- name: Meetings
paths:
  /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'
  /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 page''s project'
components:
  schemas:
    Attachments_Model:
      allOf:
      - $ref: '#/components/schemas/CollectionModel'
      - type: object
        required:
        - _links
        - _embedded
        properties:
          _links:
            type: object
            required:
            - self
            properties:
              self:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'The attachments collection


                    **Resource**: AttachmentsCollection'
                  readOnly: true
          _embedded:
            type: object
            properties:
              elements:
                type: array
                readOnly: true
                items:
                  allOf:
                  - $ref: '#/components/schemas/AttachmentModel'
                  - description: Collection of Attachments
    MeetingCollectionModel:
      allOf:
      - $ref: '#/components/schemas/PaginatedCollectionModel'
      - type: object
        required:
        - _embedded
        - _links
        properties:
          _embedded:
            type: object
            required:
            - elements
            properties:
              elements:
                type: array
                items:
                  $ref: '#/components/schemas/MeetingModel'
          _links:
            type: object
            required:
            - self
            properties:
              self:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'The link to this meeting collection resource


                    **Resource**: MeetingCollection'
    CollectionLinks:
      type: object
      required:
      - self
      properties:
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
          - description: 'This collection resource.


              **Resource**: Collection'
    AttachmentModel:
      type: object
      required:
      - fileName
      - description
      - status
      - contentType
      - digest
      - createdAt
      properties:
        id:
          type: integer
          description: Attachment's id
          minimum: 1
        fileName:
          type: string
          description: The name of the uploaded file
        fileSize:
          type: integer
          description: The size of the uploaded file in Bytes
          minimum: 0
        description:
          allOf:
          - $ref: '#/components/schemas/Formattable'
          - description: A user provided description of the file
        status:
          type: string
          enum:
          - uploaded
          - prepared
          - scanned
          - quarantined
          - rescan
        contentType:
          type: string
          description: The files MIME-Type as determined by the server
        digest:
          type: object
          description: A checksum for the files content
          required:
          - algorithm
          - hash
          properties:
            algorithm:
              type: string
              description: The algorithm used to generate the digest.
            hash:
              type: string
              description: The hexadecimal representation of the digested hash value.
        createdAt:
          type: string
          format: date-time
          description: Time of creation
        _links:
          type: object
          required:
          - self
          - container
          - author
          - downloadLocation
          properties:
            delete:
              allOf:
              - $ref: '#/components/schemas/Link'
              - description: 'Deletes this attachment


                  # Conditions


                  **Permission**: edit on attachment container or being the author for attachments without container'
            self:
              allOf:
              - $ref: '#/components/schemas/Link'
              - description: 'This attachment


                  **Resource**: Attachment'
            container:
              allOf:
              - $ref: '#/components/schemas/Link'
              - description: 'The object (e.g. WorkPackage) housing the attachment


                  **Resource**: Anything'
            author:
              allOf:
              - $ref: '#/components/schemas/Link'
              - description: 'The user who uploaded the attachment


                  **Resource**: User'
            downloadLocation:
              allOf:
              - $ref: '#/components/schemas/Link'
              - description: 'Direct download link to the attachment


                  **Resource**: -'
      example:
        _type: Attachment
        _links:
          self:
            href: /api/v3/attachments/1
          container:
            href: /api/v3/work_packages/1
          author:
            href: /api/v3/users/1
          staticDownloadLocation:
            href: /api/v3/attachments/1/content
          downloadLocation:
            href: /some/remote/aws/url/image.png
        id: 1
        fileName: cat.png
        filesize: 24
        status: uploaded
        description:
          format: plain
          raw: A picture of a cute cat
          html: <p>A picture of a cute cat</p>
        contentType: image/png
        digest:
          algorithm: md5
          hash: 64c26a8403cd796ea4cf913cda2ee4a9
        createdAt: '2014-05-21T08:51:20.396Z'
    CustomFieldProperties:
      type: object
      patternProperties:
        ^customField\d+$:
          type:
          - 'null'
          - number
          - boolean
          - string
          - object
          description: 'A custom field value, that belongs to a custom field of a simple type:


            - Boolean

            - Date

            - Float

            - Integer

            - Link (URL)

            - Text

            - Long text'
    Link:
      type: object
      required:
      - href
      properties:
        href:
          type:
          - string
          - 'null'
          description: URL to the referenced resource (might be relative)
        title:
          type: string
          description: Representative label for the resource
        templated:
          type: boolean
          default: false
          description: If true the href contains parts that need to be replaced by the client
        method:
          type: string
          default: GET
          description: The HTTP verb to use when requesting the resource
        payload:
          type: object
          description: The payload to send in the request to achieve the desired result
        identifier:
          type: string
          description: An optional unique identifier to the link object
        type:
          type: string
          description: The MIME-Type of the returned resource.
      example:
        href: /api/v3/work_packages
        method: POST
    Formattable:
      type: object
      required:
      - format
      properties:
        format:
          type: string
          enum:
          - plain
          - markdown
          - custom
          readOnly: true
          description: Indicates the formatting language of the raw text
          example: markdown
        raw:
          type: string
          description: The raw text, as entered by the user
          example: I **am** formatted!
        html:
          type: string
          readOnly: true
          description: The text converted to HTML according to the format
          example: I <strong>am</strong> formatted!
      example:
        format: markdown
        raw: I am formatted!
        html: I am formatted!
    ProjectModel:
      allOf:
      - $ref: '#/components/schemas/CustomFieldProperties'
      - $ref: '#/components/schemas/CustomCommentProperties'
      - type: object
        properties:
          _type:
            type: string
            enum:
            - Project
          id:
            type: integer
            description: Projects' id
            minimum: 1
          identifier:
            type: string
          name:
            type: string
          active:
            type: boolean
            description: Indicates whether the project is currently active or already archived
          favorited:
            type: boolean
            description: Indicates whether the project is favorited by the current user
          statusExplanation:
            allOf:
            - $ref: '#/components/schemas/Formattable'
            - description: A text detailing and explaining why the project has the reported status
          public:
            type: boolean
            description: Indicates whether the project is accessible for everybody
          description:
            $ref: '#/components/schemas/Formattable'
          createdAt:
            type: string
            format: date-time
            description: Time of creation. Can be writable by admins with the `apiv3_write_readonly_attributes` setting enabled.
          updatedAt:
            type: string
            format: date-time
            description: Time of the most recent change to the project
          _links:
            type: object
            required:
            - self
            - categories
            properties:
              update:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'Form endpoint that aids in updating this project


                    # Conditions


                    **Permission**: edit workspace'
              updateImmediately:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'Directly update this project


                    # Conditions


                    **Permission**: edit workspace'
              delete:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'Delete this project


                    # Conditions


                    **Permission**: admin'
              favor:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'Mark this project as favorited by the current user


                    # Conditions


                    Only present if the project is not yet favorited


                    Permission**: none but login is required'
              disfavor:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'Mark this project as not favorited by the current user


                    # Conditions

                    Only present if the project is favorited by the current user


                    Permission**: none but login is required'
              createWorkPackage:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'Form endpoint that aids in preparing and creating a work package


                    # Conditions


                    **Permission**: add work packages'
              createWorkPackageImmediately:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'Directly creates a work package in the project


                    # Conditions


                    **Permission**: add work packages'
              self:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'This project


                    **Resource**: Project'
              categories:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'Categories available in this project


                    **Resource**: Collection'
              types:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'Types available in this project


                    **Resource**: Collection


                    # Conditions


                    **Permission**: view work packages or manage types'
              versions:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'Versions available in this project


                    **Resource**: Collection


                    # Conditions


                    **Permission**: view work packages or manage versions'
              memberships:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'Memberships in the project


                    **Resource**: Collection


                    # Conditions


                    **Permission**: view members'
              workPackages:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'Work Packages of this project


                    **Resource**: Collection'
              parent:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'Parent of the project


                    **Resource**: Workspace


                    # Conditions


                    **Permission** edit workspace'
              status:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'Denotes the status of the project, so whether the project is on track, at risk or is having trouble.


                    **Resource**: ProjectStatus


                    # Conditions


                    **Permission** edit workspace'
              storages:
                type: array
                items:
                  allOf:
                  - $ref: '#/components/schemas/Link'
                  - description: 'The link to a storage that is active for this project.


                      **Resource**: Storage


                      # Conditions


                      **Permission**: view_file_links'
              projectStorages:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'The project storage collection of this project.


                    **Resource**: Collection


                    # Conditions


                    **Permission**: view_file_links'
              ancestors:
                type: array
                items:
                  allOf:
                  - $ref: '#/components/schemas/Link'
                  - description: 'A collection of links to the ancestor workspaces.


                      **Resource**: Workspace'
    PaginatedCollectionModel:
      allOf:
      - $ref: '#/components/schemas/CollectionModel'
      - type: object
        required:
        - pageSize
        - offset
        properties:
          pageSize:
            type: integer
            description: Amount of elements that a response will hold.
            minimum: 0
          offset:
            type: integer
            description: The page number that is requested from paginated collection.
            minimum: 1
          _links:
            type: object
            required:
            - jumpTo
            - changeSize
            properties:
              jumpTo:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'Templated link to another page offset.


                    **Resource**: Collection'
              changeSize:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'Templated link for another page size.


                    **Resource**: Collection'
    UserModel:
      allOf:
      - $ref: '#/components/schemas/PrincipalModel'
      - $ref: '#/components/schemas/CustomFieldProperties'
      - type: object
        required:
        - _type
        - avatar
        properties:
          _type:
            type: string
            enum:
            - User
          avatar:
            type:
            - string
            - 'null'
            format: uri
            description: URL to user's avatar
          login:
            type: string
            description: 'The user''s login name


              # Conditions


              - User is self, or `create_user` or `manage_user` permission globally'
            maxLength: 256
          firstName:
            type: string
            description: 'The user''s first name


              # Conditions


              - User is self, or `create_user` or `manage_user` permission globally'
            maxLength: 30
          lastName:
            type: string
            description: 'The user''s last name


              # Conditions


              - User is self, or `create_user` or `manage_user` permission globally'
            maxLength: 30
          email:
            type: string
            description: 'The user''s email address


              # Conditions


              - E-Mail address not hidden

              - User is not a new record

              - User is self, or `create_user` or `manage_user` permission globally'
            maxLength: 60
          admin:
            type: boolean
            description: 'Flag indicating whether or not the user is an admin


              # Conditions


              - `admin`'
          status:
            type: string
            description: 'The current activation status of the user.


              # Conditions


              - User is self, or `create_user` or `manage_user` permission globally'
          language:
            type: string
            description: 'User''s language | ISO 639-1 format


              # Conditions


              - User is self, or `create_user` or `manage_user` permission globally'
          identityUrl:
            type:
            - string
            - 'null'
            description: 'User''s identity_url for OmniAuth authentication.

              **Deprecated:** It will be removed in the near future.


              # Conditions


              - User is self, or `create_user` or `manage_user` permission globally'
            deprecated: true
          createdAt:
            type: string
            format: date-time
            description: Time of creation
          updatedAt:
            type: string
            format: date-time
            description: Time of the most recent change to the user
          _links:
            type: object
            properties:
              showUser:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'A relative path to show the user in the web application.


                    # Condition


                    - User is not a new record

                    - User is not `locked`'
              updateImmediately:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'A link to update the user resource.


                    # Conditions


                    - `admin`'
              lock:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'Restrict the user from logging in and performing any actions.


                    # Conditions


                    - User is not locked

                    - `admin`'
              unlock:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'Allow a locked user to login and act again.


                    # Conditions


                    - User is not locked

                    - `admin`'
              delete:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: "Permanently remove a user from the instance\n\n# Conditions\n\neither:\n  - `admin`\n  - Setting `users_deletable_by_admin` is set\nor:\n  - User is self\n  - Setting `users_deletable_by_self` is set"
              authSource:
                allOf:
                - $ref: '#/components/schemas/Link'
                - description: 'Permanently remove a user from the instance


                    # Conditions


                    - LDAP authentication configured

                    - `admin`'
    ErrorResponse:
      type: object
      required:
      - _type
      - errorIdentifier
      - message
      properties:
        _embedded:
          type: object
          properties:
            details:
              type: object
              properties:
                attribute:
                  type: string
                  example: project
        _type:
          type: string
          enum:
          - Error
        errorIdentifier:
          type: string
          example: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
        message:
          type: string
          example: Project can't be blank.
    PrincipalModel:
      type: object
      required:
      - _type
      - id
      - name
      - _links
      properties:
        _type:
          type: string
          enum:
          - User
          - Group
          - PlaceholderUser
        id:
          type: integer
          description: The principal's unique identifier.
          minimum: 1
        name:
          type: string
          description: The principal's display name, layout depends on instance settings.
        createdAt:
          type: string
          format: date-time
          description: Time of creation
        updatedAt:
          type: string
          format: date-time
          description: Time of the most recent change to the principal
        _links:
          type: object
          required:
          - self
          properties:
            self:
              allOf:
              - $ref: '#/components/schemas/Link'
              - description: 'This principal resource.


                  **Resource**: User|Group|PlaceholderUser'
            memberships:
              allOf:
              - $ref: '#/components/schemas/Link'
              - description: 'An href to the collection of the principal''s memberships.


                  # Conditions:


                  - user has permission `view_members` or `manage_members` in any project


                  **Resource**: Collection'
    CustomCommentProperties:
      type: object
      patternProperties:
        ^customComment\d+$:
          type:
          - 'null'
          - string
          description: 'A plain-text comment associated with a project custom field that has comments enabled.


            The property is only present when the corresponding `customField{N}` has `has_comment` set to `true`.'
    CollectionModel:
      type: object
      required:
      - _type
      - total
      - count
      - _links
      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
        _links:
          $ref: '#/components/schemas/CollectionLinks'
    MeetingModel:
      type: object
      required:
      - _type
      - id
      - lockVersion
      - title
      - startTime
      - endTime
      - duration
      - createdAt
      - updatedAt
      properties:
        _type:
          type: string
          enum:
          - Meeting
        id:
          type: integer
          description: Identifier of this meeting
          minimum: 1
        title:
          type: string
          description: The meeting's title
        location:
          type: string
          description: The meeting's location
        lockVersion:
          type: integer
          description: The version of the item as used for optimistic locking
        startTime:
          type: string
          format: date-time
          description: The scheduled meeting start time.
        endTime:
          type: string
          format: date-time
          description: The scheduled meeting start time.
        duration:
          type: number
          description: The meeting duration in hours.
        createdAt:
          type: string
          format: date-time
          description: Time of creation. Can be writable by admins with the `apiv3_write_readonly_attributes` setting enabled.
        updatedAt:
          type: string
          format: date-time
          description: Time of the most recent change to the meeting.
        _embedded:
          type: object
          required:
          - attachments
          - author
          properties:
            attachments:
              $ref: '#/components/schemas/Attachments_Model'
            author:
              $ref: '#/components/schemas/UserModel'
            project:
              $ref: '#/components/schemas/ProjectModel'
        _links:
          type: object
          properties:
            self:
              allOf:
              - $ref: '#/components/schemas/Link'
              - description: 'This meeting


                  **Resource**: Meeting'
            author:
              allOf:
              - $ref: '#/components/schemas/Link'
              - description: 'The user having created the meeting


                  **Resource**: User'
            project:
              allOf:
              - $ref: '#/components/schemas/Link'
              - description: 'The project the meeting is in


                  **Resource**: Project'
            attachments:
              allOf:
              - $ref: '#/components/schemas/Link'
              - description: 'The attachment collection of this grid.


                  **Resource**: AttachmentCollection'
            addAttachment:
              allOf:
              - $ref: '#/components/schemas/Link'
              - description: 'Attach a file to the meeting


                  # Conditions


                  **Permission**: edit meeting'
  examples:
    MeetingSimpleResponse:
      description: A simple meeting response.
      value:
        _type: Meeting
        id: 1
        title: Meeting No 42
        location: Death Star - Level 1337 L13/42
        lockVersion: 13
        startTime: '2026-02-16T10:00:00.000Z'
        endTime: '2026-02-16T11:00:00.000Z'
        duration: 1.0
        createdAt: '2026-02-13T14:47:12.315Z'
        updatedAt: '2026-02-13T14:47:12.315Z'
        _links:
          attachments:
            href: /api/v3/meetings/1/attachments
          addAttachment:
            href: /api/v3/meetings/1/attachments
            method: post
          self:
            href: /api/v3/meetings/1
            title: Meeting No 42
          author:
            href: /api/v3/users/4
            title: Darth Vader
          project:
            href: /api/v3/projects/10
            title: Death Star
        _embedded:
          _abbreviated: Embedded resources shortened for brevity
          attachments:
            _type: Collection
            total: 2
            count: 2
          author:
            _type: User
            name: Darth Vader
            id: 4
          project:
            _type: Project
            name: Death Star
            id: 10
    MeetingCollectionSimpleResponse:
      description: A simple response of a meeting collection.
      value:
        _type: Collection
        total: 2
        count: 2
        pageSize: 20
        offset: 1
        _embedded:
          _abbreviated: Embedded resources shortened for brevity
          elements:
          - _type: Meeting
            id: 6
            title: Weekly
            startTime: '2026-02-17T20:54:35.523Z'
            endTime: '2026-02-17T21:54:35.523Z'
          - _type: Meeting
            id: 5
            title: Weekly
            startTime: '2026-02-10T20:54:35.523Z'
            endTime: '2026-02-10T21:54:35.523Z'
        _links:
          self:
            href: /api/v3/meetings?filters=%5B%5D&offset=1&pageSize=20
          jumpTo:
            href: /api/v3/meetings?filters=%5B%5D&offset=%7Boffset%7D&pageSize=20
            templated: true
          changeSize:
            href: /api/v3/meetings?filters=%5B%5D&offset=1&pageSize=%7Bsize%7D
            templated: true
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic