API: Configuration

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

Methods

View configuration

No parameters

200

OK

{
  "_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"
  ]
}
ConfigurationModel
{
  "type": "object",
  "properties": {
    "maximumAttachmentFileSize": {
      "type": "integer",
      "description": "The maximum allowed size of an attachment in Bytes",
      "readOnly": true
    },
    "hostName": {
      "type": "string",
      "description": "The host name configured for the system",
      "readOnly": true
    },
    "perPageOptions": {
      "type": "array",
      "description": "Page size steps to be offered in paginated list UI",
      "items": {
        "type": "integer"
      }
    },
    "durationFormat": {
      "type": "string",
      "description": "The format used to display Work, Remaining Work, and Spent time durations",
      "readOnly": true
    },
    "activeFeatureFlags": {
      "type": "array",
      "description": "The list of all feature flags that are active",
      "items": {
        "type": "string"
      }
    }
  }
}

View project configuration

Returns the configuration scoped to a specific project, including all global configuration properties plus project-specific settings.

id
integer

required path

Project id

Example:
1

200

OK

{
  "_type": "Configuration",
  "_links": {
    "self": {
      "href": "/api/v3/projects/1/configuration"
    },
    "userPreferences": {
      "href": "/api/v3/my_preferences"
    }
  },
  "maximumAttachmentFileSize": 5242880,
  "perPageOptions": [
    20,
    100
  ],
  "enabledInternalComments": true
}
ProjectConfigurationModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/ConfigurationModel"
    },
    {
      "type": "object",
      "properties": {
        "enabledInternalComments": {
          "type": "boolean",
          "description": "Whether internal comments are enabled for this project",
          "readOnly": true
        }
      }
    }
  ]
}

404

Returned if the project does not exist or the user cannot view it.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
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."
    }
  }
}