OpenProject

aid: openproject
name: OpenProject
description: OpenProject is an open source project management platform offering work package tracking, Gantt charts, agile
  boards, time tracking, BIM, and enterprise project portfolio management. The OpenProject APIv3 is a hypermedia (HAL+JSON)
  REST API that exposes work packages, projects, users, attachments, custom fields, and many other resources.
type: Index
accessModel:
  pricing: freemium
  onboarding: self-serve
  trial: false
  try_now: true
  public: false
  label: Freemium · Self-serve signup
  confidence: high
  source:
  - plans
  - authentication
  generated: '2026-07-22'
  method: derived
position: Consumer
access: 3rd-Party
image: https://kinlane-images.s3.amazonaws.com/shared/apis-json/icons/openproject.png
tags:
- Agile
- Gantt
- Open Source
- Project Management
- Time Tracking
- Work Packages
created: '2025-01-08'
modified: '2026-05-19'
url: https://raw.githubusercontent.com/api-evangelist/openproject/refs/heads/main/apis.yml
specificationVersion: '0.19'
apis:
- aid: openproject:openproject-actions-capabilities-api
  name: OpenProject Actions & Capabilities API
  description: 'An action is a change one can trigger within the OpenProject instance.

    This could be creating a work package, exporting work packages or updating a user.

    An action can also be something where the user is able to be involved so where the user is in the passive role

    e.g. when being assigned a work package.


    A capability combines an action with a context and a principal. It thus communicates, which principal can carry out

    (or be passively involved) which action within a certain context. E.g. a user might have the capability of creating work
    packages

    within a project.


    In other words, an action is independent of a principal and context while a capability is

    a relation between an action, the context and the principal.


    The actions are most of the time derived from permissions which can be configured via the administrative UI where an administrator

    selects from a set of permissions to be granted per role. But there are other cases, e.g. in order to become assignee
    or responsible of a work package, a user has

    to have a role which allows having work packages assigned which is not a permission.


    Even though user might have a capability, it might still not be possible to carry out the action

    because some other requirement is not met.

    E.g. a user might have the capability to update work packages, but if a particular work package is

    in a readonly state, that work package cannot be updated.


    *Only a small set of actions that actually already exist in the system are currently exposed via

    the api. They will be added over time.*


    ## Action


    An action describes what can be carried out within the application. Until an action becomes assigned,

    which turns it into a capability, it remains in the state of "could be".


    ### Linked Properties


    |  Link               | Description                              | Type             | Constraints                                                    |
    Supported operations |

    |:-------------------:|----------------------------------------- | -------------    | --------------------------------------------------------------
    | -------------------- |

    | self                | The action                               | Action           | not null                                                       |
    READ                 |


    ### Local Properties


    | Property    | Description                                                                             | Type        |
    Constraints    | Supported operations |

    | :---------: | ---------------------------------------------                                           | -----------
    | -----------    | -------------------- |

    | id          | Identifier for the action                                                               | String      |
    Not null       | READ                 |

    | name        | A human readable name for the action *Not yet implemented*                              | String      |
    Not null       | READ                 |

    | description | Describes what can be done by principals having that action   *Not yet implemented*     | String      |
    Not null       | READ                 |

    | modules     | Clusters the actions into groups into which they belong logically *Not yet implemented* | []String    |
    Not null       | READ                 |


    ## Capabilities


    Actions can be assigned to a principal by assigning roles to that principal. E.g. a user might receive the ''work_packages/show''

    action by having a role called reader assigned within a project.


    Whenever a principal is assigned an action within a context, the principal has additional capabilities.


    Exactly which actions can be gained by having a role assigned depends on the configuration of that role.

    The configuration is adaptable by admins within the administration of the OpenProject instance.


    ### Linked Properties


    |  Link               | Description                                                                                            |
    Type               | Constraints     | Supported operations |

    |-------------------- |-----------------------------------------                                                               |
    -------------      | --------------- | -------------------- |

    | self                | The capability                                                                                         |                    |                 |                      |

    | action              | The action the principal is granted                                                                    |
    Action             | not null        | READ                 |

    | context             | The context the principal has this the action in. This is typically a workspace or the global
    context. | Workspace or null  |                 | READ                 |

    | principal           | The principal being allowed the action.                                                                |
    Action             | not null        | READ                 |


    ### Local Properties


    | Property    | Description                                   | Type        | Constraints        | Supported operations
    |

    | :---------: | --------------------------------------------- | ----------- | -----------        | --------------------
    |

    | id          | Identifier for the action                     | String      | Not null           | READ                 |

    | name        | A human readable name for the action          | String      | Not null           | READ                 |'
  humanURL: https://www.openproject.org/docs/api/
  baseURL: https://community.openproject.org/api/v3
  tags:
  - Actions & Capabilities
  properties:
  - type: OpenAPI
    url: openapi/openproject-actions-capabilities-api-openapi.yml
  - type: Documentation
    url: https://www.openproject.org/docs/api/
  - type: Introduction
    url: https://www.openproject.org/docs/api/introduction/
  - type: Endpoints
    url: https://www.openproject.org/docs/api/endpoints/
  - type: GitHub
    url: https://github.com/opf/openproject
- aid: openproject:openproject-activities-api
  name: OpenProject Activities API
  description: '## Local Properties


    | Property    | Description      | Type                 | Constraints | Supported operations |

    | :---------: | -------------    | ----                 | ----------- | -------------------- |

    | id          | Activity id      | Integer              | x > 0       | READ                 |

    | version     | Activity version | Integer              | x > 0       | READ                 |

    | comment     |                  | Formattable          |             | READ / WRITE         |

    | details     |                  | Array of Formattable |             | READ                 |

    | createdAt   | Time of creation | DateTime             |             | READ                 |

    | updatedAt   | Time of update   | DateTime             |             | READ                 |


    Activity can be either _type `Activity` or _type `Activity::Comment`.'
  humanURL: https://www.openproject.org/docs/api/
  baseURL: https://community.openproject.org/api/v3
  tags:
  - Activities
  properties:
  - type: OpenAPI
    url: openapi/openproject-activities-api-openapi.yml
  - type: Documentation
    url: https://www.openproject.org/docs/api/
  - type: Introduction
    url: https://www.openproject.org/docs/api/introduction/
  - type: Endpoints
    url: https://www.openproject.org/docs/api/endpoints/
  - type: GitHub
    url: https://github.com/opf/openproject
- aid: openproject:openproject-attachments-api
  name: OpenProject Attachments API
  description: 'Attachments are files that were uploaded to OpenProject. Each attachment belongs to a single

    container (e.g. a work package or a board message).


    ## Actions


    | Link                | Description                                                          | Condition                                                                                          |

    |:-------------------:|----------------------------------------------------------------------| --------------------------------------------                                                       |

    | delete              | Deletes this attachment                                              | **Permission**: edit on
    attachment container or being the author for attachments without container |


    ## Linked Properties


    |  Link            | Description                                         | Type          | Constraints | Supported operations
    |

    |:----------------:| --------------------------------------------------- | ------------- | ----------- | --------------------
    |

    | self             | This attachment                                     | Attachment    | not null    | READ                 |

    | container        | The object (e.g. WorkPackage) housing the attachment| Anything      | not null    | READ                 |

    | author           | The user who uploaded the attachment                | User          | not null    | READ                 |

    | downloadLocation | Direct download link to the attachment              | -             | not null    | READ                 |


    ## Local Properties


    | Property     | Description                                     | Type        | Constraints | Supported operations |

    |:------------:| ----------------------------------------------- | ----------- | ----------- | -------------------- |

    | id           | Attachment''s id                                 | Integer     | x > 0       | READ                 |

    | title        | The name of the file                            | String      | not null    | READ                 |

    | fileName     | The name of the uploaded file                   | String      | not null    | READ                 |

    | fileSize     | The size of the uploaded file in Bytes          | Integer     | x >= 0      | READ                 |

    | description  | A user provided description of the file         | Formattable | not null    | READ                 |

    | contentType  | The files MIME-Type as determined by the server | String      | not null    | READ                 |

    | digest       | A checksum for the files content                | Digest      | not null    | READ                 |

    | createdAt    | Time of creation                                | DateTime    | not null    | READ                 |'
  humanURL: https://www.openproject.org/docs/api/
  baseURL: https://community.openproject.org/api/v3
  tags:
  - Attachments
  properties:
  - type: OpenAPI
    url: openapi/openproject-attachments-api-openapi.yml
  - type: Documentation
    url: https://www.openproject.org/docs/api/
  - type: Introduction
    url: https://www.openproject.org/docs/api/introduction/
  - type: Endpoints
    url: https://www.openproject.org/docs/api/endpoints/
  - type: GitHub
    url: https://github.com/opf/openproject
- aid: openproject:openproject-budgets-api
  name: OpenProject Budgets API
  description: '*Note: Budgets are currently only implemented as a stub. Further properties of budgets might be added at a
    future date, however they will require the view budget permission to be displayed.*


    ## Linked Properties:


    |  Link     | Description                                 | Type          | Constraints           | Supported operations
    |

    |:---------:|-------------------------------------------- | ------------- | --------------------- | --------------------
    |

    | self      | This budget                                 | Budget        | not null              | READ                 |


    ## Properties


    | Property    | Description                                 | Type        | Constraints | Supported operations | Condition                   |

    | :---------: | ------------------------------------------- | ----------- | ----------- | -------------------- | ---------------------------
    |

    | id          | Budget id                                   | Integer     | x > 0       | READ                 |                             |

    | subject     | Budget name                                 | String      | not empty   | READ                 |                             |'
  humanURL: https://www.openproject.org/docs/api/
  baseURL: https://community.openproject.org/api/v3
  tags:
  - Budgets
  properties:
  - type: OpenAPI
    url: openapi/openproject-budgets-api-openapi.yml
  - type: Documentation
    url: https://www.openproject.org/docs/api/
  - type: Introduction
    url: https://www.openproject.org/docs/api/introduction/
  - type: Endpoints
    url: https://www.openproject.org/docs/api/endpoints/
  - type: GitHub
    url: https://github.com/opf/openproject
- aid: openproject:openproject-categories-api
  name: OpenProject Categories API
  description: 'The categories endpoints return collections or single entities of type `Category`. The following tables list
    the different properties

    of `Category` entities.


    ## Linked Properties


    |  Link           | Description                                         | Type          | Constraints | Supported operations
    |

    |:---------------:| --------------------------------------------------- | ------------- | ----------- | --------------------
    |

    | self            | This category                                       | Category      | not null    | READ                 |

    | project         | The project of this category                        | Project       | not null    | READ                 |

    | defaultAssignee | Default assignee for work packages of this category | User          |             | READ                 |


    ## Local Properties


    | Property   | Description   | Type    | Constraints | Supported operations |

    | :--------: | ------------- | ------- | ----------- | -------------------- |

    | id         | Category id   | Integer | x > 0       | READ                 |

    | name       | Category name | String  |             | READ                 |'
  humanURL: https://www.openproject.org/docs/api/
  baseURL: https://community.openproject.org/api/v3
  tags:
  - Categories
  properties:
  - type: OpenAPI
    url: openapi/openproject-categories-api-openapi.yml
  - type: Documentation
    url: https://www.openproject.org/docs/api/
  - type: Introduction
    url: https://www.openproject.org/docs/api/introduction/
  - type: Endpoints
    url: https://www.openproject.org/docs/api/endpoints/
  - type: GitHub
    url: https://github.com/opf/openproject
- aid: openproject:openproject-collections-api
  name: OpenProject Collections API
  description: 'Whenever a client calls a resource that can return more than one element, it will receive a collection of
    elements.

    However as collections can become quite large, the API will **not** simply return a JSON array, but a special collection

    object that will contain the actual elements in its embedded property `elements`.


    Collections *may* be paginated, this means that a single response from the server will not contain all elements of the
    collection,

    but only a subset. In this case the client can issue further requests to retrieve the remaining elements.

    There are two ways to access the result pages of a paginated collection:


    * offset based pagination


    * cursor based pagination


    The available ways of pagination depend on the collection queried. Some collections feature no pagination at all, meaning
    they

    will always return all elements. Others might only offer one of the two pagination methods or both of them.


    A collection also carries meta information like the total count of elements in the collection or - in case of a paginated
    collection -

    the amount of elements returned in this response and action links to retrieve the remaining elements.


    ## Local Properties


    | Property | Description                                                     | Type    | Availability                |

    |:--------:| --------------------------------------------------------------- | ------- | --------------------------- |

    | total    | The total amount of elements available in the collection        | Integer | always                      |

    | pageSize | Amount of elements that a response will hold                    | Integer | when paginated              |

    | count    | Actual amount of elements in this response                      | Integer | always                      |

    | offset   | The page number that is requested from paginated collection     | Integer | when offset based available |

    | groups   | Summarized information about aggregation groups                 | Object  | when grouping               |

    | totalSums| Aggregations of supported values for elements of the collection | Object  | when showing sums           |


    ## Links


    | Link             | Description                                                              | Availability                |

    |:----------------:| ------------------------------------------------------------------------ | ---------------------------
    |

    | self             | Link to the current page in the collection                               | always                      |

    | changeSize       | Templated link to change the page size, might change relative position   | when paginated              |

    | jumpTo           | Templated link to jump to a specified offset                             | when offset based available
    |

    | nextByOffset     | Link to retrieve the following page of elements (offset based)           | when offset based available
    |

    | previousByOffset | Link to retrieve the preceding page of elements (offset based)           | when offset based available
    |

    | nextByCursor     | Link to retrieve the elements following the current page (cursor based)  | when cursor based available
    |

    | previousByCursor | Link to retrieve the elements preceding the current page (cursor based)  | when cursor based available
    |'
  humanURL: https://www.openproject.org/docs/api/
  baseURL: https://community.openproject.org/api/v3
  tags:
  - Collections
  properties:
  - type: OpenAPI
    url: openapi/openproject-collections-api-openapi.yml
  - type: Documentation
    url: https://www.openproject.org/docs/api/
  - type: Introduction
    url: https://www.openproject.org/docs/api/introduction/
  - type: Endpoints
    url: https://www.openproject.org/docs/api/endpoints/
  - type: GitHub
    url: https://github.com/opf/openproject
- aid: openproject:openproject-configuration-api
  name: OpenProject Configuration API
  description: 'The configuration endpoint allows to read certain configuration parameters of the OpenProject instance.

    Note that there is no 1:1 relationship between this endpoint and the settings an administrator has at hand to modify the
    behaviour

    of the application via configuration.yml or ENV variables.


    For now this endpoint will only allow access to settings deemed useful for a client to know in general.


    As clients might rely on the combination of both, the system settings as well as the current user''s preferences, the
    resource

    embeds the current user''s preferences so client can fetch both with one request.


    | Link                | Description                                      | Type            | Nullable | Supported operations
    |

    |:-------------------:| ------------------------------------------------ | -------------   | -------- | --------------------
    |

    | self                | The configuration                                | Configuration   |          | READ                 |

    | userPreferences     | The preferences of the current user              | UserPreferences |          | READ                 |


    ## Local Properties


    | Property                  | Description                                                                | Type       |
    Condition         | Supported operations |

    | :-----------------------: | -------------------------------------------------------------------------- | ----------
    | ----------------- | -------------------- |

    | maximumAttachmentFileSize | The maximum allowed size of an attachment in Bytes                         | Integer    |                   |
    READ                 |

    | perPageOptions            | Page size steps to be offered in paginated list UI                         | Integer[]  |                   |
    READ                 |

    | hostName                  | The host name configured for the system                                    | String     |                   |
    READ                 |

    | durationFormat            | The format used to display Work, Remaining Work, and Spent time durations. | String     |                   |
    READ                 |

    | activeFeatureFlags        | The list of all feature flags that are active                              | String[]   |                   |
    READ                 |'
  humanURL: https://www.openproject.org/docs/api/
  baseURL: https://community.openproject.org/api/v3
  tags:
  - Configuration
  properties:
  - type: OpenAPI
    url: openapi/openproject-configuration-api-openapi.yml
  - type: Documentation
    url: https://www.openproject.org/docs/api/
  - type: Introduction
    url: https://www.openproject.org/docs/api/introduction/
  - type: Endpoints
    url: https://www.openproject.org/docs/api/endpoints/
  - type: GitHub
    url: https://github.com/opf/openproject
- aid: openproject:openproject-custom-actions-api
  name: OpenProject Custom actions API
  description: 'Custom actions are a preconfigured set of changes that are applied to a work package.


    Currently, this resource is a stub. The conditions and changes defined for the custom action are not yet present in the
    resource.


    ## Actions


    | Link                | Description                                                          | Condition                                                                                                                        |

    |:-------------------:|----------------------------------------------------------------------| ---------------------------------------                                                                                          |

    | executeImmediately  | Apply the action to a work package                                   |


    ## Linked Properties


    | Property         | Description                                               | Type                  | Constraints                      |
    Supported operations |

    | :--------------: | ------------------------------------------------------    | -----------           | --------------------------------
    | -------------------- |

    | self             | This custom action                                        | CustomAction          | not null                         |
    READ                 |


    ## Local Properties


    | Property         | Description                                              | Type                  | Constraints  |
    Supported operations |

    | :--------------: | ------------------------------------------------------   | -----------           | ------------ |
    -------------------- |

    | id               | Custom action id                                         | Integer               | x > 0        |
    READ                 |

    | name             | The user selected name of the custom action              | String                |              |
    READ                 |

    | description      | A text describing the custom action                      | String                |              |
    READ                 |'
  humanURL: https://www.openproject.org/docs/api/
  baseURL: https://community.openproject.org/api/v3
  tags:
  - Custom actions
  properties:
  - type: OpenAPI
    url: openapi/openproject-custom-actions-api-openapi.yml
  - type: Documentation
    url: https://www.openproject.org/docs/api/
  - type: Introduction
    url: https://www.openproject.org/docs/api/introduction/
  - type: Endpoints
    url: https://www.openproject.org/docs/api/endpoints/
  - type: GitHub
    url: https://github.com/opf/openproject
- aid: openproject:openproject-custom-field-items-api
  name: OpenProject Custom Field Items API
  description: The Custom Field Items API from OpenProject — 2 operation(s) for custom field items.
  humanURL: https://www.openproject.org/docs/api/
  baseURL: https://community.openproject.org/api/v3
  tags:
  - Custom Field Items
  properties:
  - type: OpenAPI
    url: openapi/openproject-custom-field-items-api-openapi.yml
  - type: Documentation
    url: https://www.openproject.org/docs/api/
  - type: Introduction
    url: https://www.openproject.org/docs/api/introduction/
  - type: Endpoints
    url: https://www.openproject.org/docs/api/endpoints/
  - type: GitHub
    url: https://github.com/opf/openproject
- aid: openproject:openproject-custom-fields-api
  name: OpenProject Custom Fields API
  description: The Custom Fields API from OpenProject — 1 operation(s) for custom fields.
  humanURL: https://www.openproject.org/docs/api/
  baseURL: https://community.openproject.org/api/v3
  tags:
  - Custom Fields
  properties:
  - type: OpenAPI
    url: openapi/openproject-custom-fields-api-openapi.yml
  - type: Documentation
    url: https://www.openproject.org/docs/api/
  - type: Introduction
    url: https://www.openproject.org/docs/api/introduction/
  - type: Endpoints
    url: https://www.openproject.org/docs/api/endpoints/
  - type: GitHub
    url: https://github.com/opf/openproject
- aid: openproject:openproject-custom-options-api
  name: OpenProject Custom Options API
  description: 'The custom options endpoints return collections or single entities of type `CustomOption`. The following tables
    list the different properties

    of `CustomOption` entities.


    ## Linked Properties


    |  Link         | Description               | Type          | Constraints | Supported operations |

    |:-------------:|-------------------------- | ------------- | ----------- | -------------------- |

    | self          | This custom option        | CustomOption  | not null    | READ                 |


    ## Local Properties


    | Property         | Description                                    | Type     | Constraints | Supported operations |

    |:----------------:| ---------------------------------------------- | -------- | ----------- | -------------------- |

    | id               | The identifier                                 | Integer  |             | READ                 |

    | value            | The value defined for this custom option       | String   |             | READ                 |


    custom options are options of list custom fields.'
  humanURL: https://www.openproject.org/docs/api/
  baseURL: https://community.openproject.org/api/v3
  tags:
  - Custom Options
  properties:
  - type: OpenAPI
    url: openapi/openproject-custom-options-api-openapi.yml
  - type: Documentation
    url: https://www.openproject.org/docs/api/
  - type: Introduction
    url: https://www.openproject.org/docs/api/introduction/
  - type: Endpoints
    url: https://www.openproject.org/docs/api/endpoints/
  - type: GitHub
    url: https://github.com/opf/openproject
- aid: openproject:openproject-documents-api
  name: OpenProject Documents API
  description: 'A document is a file containing a list of attachments.


    *Please note, that the endpoint is only a stub for now.*


    ## Actions


    None yet


    ## Linked Properties


    | Link          | Description                               | Type           | Constraints           | Supported operations
    | Condition                                 |

    | :-----------: | -------------------------------------     | -------------  | --------------------- | --------------------
    | ----------------------------------------- |

    | self          | This document                             | Document       | not null              | READ                 |                                           |

    | project       | The project the document is in            | Project        | not null              | READ / WRITE         |                                           |

    | attachments   | The attachments belonging to the document | []Attachment   | not null              | READ / WRITE         |                                           |


    ## Local Properties


    | Property     | Description                                               | Type     | Constraints                                          |
    Supported operations | Condition                                                   |

    | :----------: | --------------------------------------------------------- | -------- | ----------------------------------------------------
    | -------------------- | ----------------------------------------------------------- |

    | id           | Document''s id                                             | Integer  | x > 0                                                |
    READ                 |                                                             |

    | title        | The title chosen for the collection of documents          | String   | max 60 characters                                    |
    READ                 |                                                             |

    | description  | A text describing the documents                           | String   |                                                      |
    READ                 |                                                             |

    | createdAt    | The time the document was created at                      | DateTime |                                                      |
    READ                 |                                                             |'
  humanURL: https://www.openproject.org/docs/api/
  baseURL: https://community.openproject.org/api/v3
  tags:
  - Documents
  properties:
  - type: OpenAPI
    url: openapi/openproject-documents-api-openapi.yml
  - type: Documentation
    url: https://www.openproject.org/docs/api/
  - type: Introduction
    url: https://www.openproject.org/docs/api/introduction/
  - type: Endpoints
    url: https://www.openproject.org/docs/api/endpoints/
  - type: GitHub
    url: https://github.com/opf/openproject
- aid: openproject:openproject-emojireactions-api
  name: OpenProject EmojiReactions API
  description: The EmojiReactions API from OpenProject — 2 operation(s) for emojireactions.
  humanURL: https://www.openproject.org/docs/api/
  baseURL: https://community.openproject.org/api/v3
  tags:
  - EmojiReactions
  properties:
  - type: OpenAPI
    url: openapi/openproject-emojireactions-api-openapi.yml
  - type: Documentation
    url: https://www.openproject.org/docs/api/
  - type: Introduction
    url: https://www.openproject.org/docs/api/introduction/
  - type: Endpoints
    url: https://www.openproje

# --- truncated at 32 KB (243 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openproject/refs/heads/main/apis.yml