API: Workspaces
Workspaces are containers for resources to be worked on and people with sets of permissions that work on the former. There is no actual workspace resource in OpenProject. Rather, it is the generic term describing:
A lot of resources reference the workspaces they are valid in, e.g. Work package and Memberships.
Before OP 17.0 only projects existed. At that point, the API v3 was already established. That is the reason why quite a number of resource have links called “project” or similar when they are in fact contained in a different type of workspace. To not break the API, the name of the link was kept. But those links can contain the other types of workspaces as well. It can thus be possible for a work package to have the following:
{
"_links": {
"project": {
"href": "/api/v3/portfolios/48",
"title: "A portfolio"
},
...
},
...
}
Accordingly, to set the workspace a resource is in, sending any workspace link to the link property will be accepted by the API.
The concept of workspaces is planned to be extended to include further types.
Methods
View workspace schema
No parameters
200
OK
{
"_dependencies": [],
"_attributeGroups": [
{
"_type": "ProjectFormCustomFieldSection",
"name": "Workspace Details",
"attributes": [
"customField30",
"customField34"
]
},
{
"_type": "ProjectFormCustomFieldSection",
"name": "Budget Information",
"attributes": [
"customField31",
"customField32",
"customField35"
]
}
],
"_links": {
"self": {
"href": "/api/v3/workspaces/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 workspace custom field",
"required": false,
"type": "Integer",
"visibility": "default",
"writable": true
},
"customField31": {
"_links": {},
"hasDefault": false,
"location": "_links",
"name": "List workspace custom field",
"required": false,
"type": "CustomOption",
"visibility": "default",
"writable": true
},
"customField32": {
"_links": {},
"hasDefault": false,
"location": "_links",
"name": "Version workspace custom field",
"required": false,
"type": "Version",
"visibility": "default",
"writable": true
},
"customField34": {
"hasDefault": false,
"name": "Boolean workspace custom field",
"required": false,
"type": "Boolean",
"visibility": "default",
"writable": true
},
"customField35": {
"hasDefault": false,
"name": "Text workspace 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": "Workspace",
"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"
}
]
},
"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
}
}
Workspaces_schemaModel{
"type": "object",
"description": "A schema for a workspace. This schema defines the attributes of a workspace.",
"properties": {
"_type": {
"type": "string",
"enum": [
"Schema"
],
"description": "The type identifier for this resource"
},
"_dependencies": {
"type": "array",
"description": "Schema dependencies (currently empty for workspaces)"
},
"_attributeGroups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"_type": {
"type": "string",
"enum": [
"ProjectFormCustomFieldSection"
],
"description": "The type identifier for this resource"
},
"id": {
"type": "integer",
"description": "The unique identifier of the custom field section"
},
"name": {
"type": "string",
"description": "The human-readable name of the custom field section"
},
"attributes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of camelCase custom field attribute names belonging to this section.\nOnly includes custom fields visible to the current user."
}
}
},
"description": "Defines the organizational structure of project custom fields into sections for UI rendering.\n\nEach attribute group represents a project attribute section containing related project attributes.\nThe sections determine how project attributes are visually organized and grouped in forms.\n\n**Key behaviors:**\n- Admin-only project attributes appear only for users with admin privileges\n- Empty sections (with no accessible project attributes) are omitted from the response\n- The order reflects the configured section positioning in admin settings\n- Each section contains only project attributes assigned to that specific section\n\n**Example structure:**\n```json\n[\n {\n \"_type\": \"ProjectFormCustomFieldSection\",\n \"name\": \"Project Details\",\n \"attributes\": [\"customField1\", \"customField3\"]\n },\n {\n \"_type\": \"ProjectFormCustomFieldSection\",\n \"name\": \"Budget Information\",\n \"attributes\": [\"customField2\", \"customField4\"]\n }\n]\n```"
},
"id": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"name": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"identifier": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"description": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"public": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"active": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"status": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"statusExplanation": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"parent": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"createdAt": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"updatedAt": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"_links": {
"type": "object",
"description": "Links related to this resource",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"example": "/api/v3/workspaces/schema"
}
}
}
}
}
},
"example": {
"_type": "Schema",
"_dependencies": [],
"_attributeGroups": [
{
"_type": "ProjectFormCustomFieldSection",
"name": "Project Details",
"attributes": "customField30 customField34"
},
{
"_type": "ProjectFormCustomFieldSection",
"name": "Budget Information",
"attributes": "customField31 customField32 customField35"
}
],
"id": {
"type": "Integer",
"name": "ID",
"required": true,
"hasDefault": false,
"writable": false
},
"name": {
"type": "String",
"name": "Name",
"required": true,
"hasDefault": false,
"writable": true,
"minLength": 1,
"maxLength": 255
},
"identifier": {
"type": "String",
"name": "Identifier",
"required": true,
"hasDefault": false,
"writable": true,
"minLength": 1,
"maxLength": 100
},
"description": {
"type": "Formattable",
"name": "Description",
"required": false,
"hasDefault": false,
"writable": true
},
"public": {
"type": "Boolean",
"name": "Public",
"required": true,
"hasDefault": false,
"writable": true
},
"active": {
"type": "Boolean",
"name": "Active",
"required": true,
"hasDefault": true,
"writable": true
},
"status": {
"type": "ProjectStatus",
"name": "Status",
"required": false,
"hasDefault": true,
"writable": true,
"_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"
}
]
}
},
"statusExplanation": {
"type": "Formattable",
"name": "Status explanation",
"required": false,
"hasDefault": false,
"writable": true
},
"parent": {
"type": "Workspace",
"name": "Subproject of",
"required": false,
"hasDefault": false,
"writable": true,
"location": "_links",
"visibility": "default",
"_links": {}
},
"createdAt": {
"type": "DateTime",
"name": "Created on",
"required": true,
"hasDefault": false,
"writable": false
},
"updatedAt": {
"type": "DateTime",
"name": "Updated on",
"required": true,
"hasDefault": false,
"writable": false
},
"customField30": {
"type": "Integer",
"name": "Integer project custom field",
"required": false,
"hasDefault": false,
"writable": true,
"visibility": "default"
},
"customField31": {
"type": "CustomOption",
"name": "List project custom field",
"required": false,
"hasDefault": false,
"writable": true,
"location": "_links",
"visibility": "default",
"_links": {}
},
"customField32": {
"type": "Version",
"name": "Version project custom field",
"required": false,
"hasDefault": false,
"writable": true,
"location": "_links",
"visibility": "default",
"_links": {}
},
"customField34": {
"type": "Boolean",
"name": "Boolean project custom field",
"required": false,
"hasDefault": false,
"writable": true,
"visibility": "default"
},
"customField35": {
"type": "String",
"name": "Text project custom field",
"required": true,
"hasDefault": false,
"writable": true,
"visibility": "default"
},
"_links": {
"self": {
"href": "/api/v3/workspaces/schema"
}
}
}
}
Favorite workspace
Adds the workspace to the current user’s favorites.
id
integer
required path
Workspace id
Example:1
204
Returned if the workspace was successfully added to favorites.
404
Returned if the workspace does not exist or the client does not have sufficient permissions to see it.
Required permission: view workspace
{
"_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."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: logged in
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
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."
}
}
}
Unfavorite workspace
Removes the workspace from the current user’s favorites.
id
integer
required path
Workspace id
Example:1
204
Returned if the workspace was successfully removed from favorites.
404
Returned if the workspace does not exist or the client does not have sufficient permissions to see it.
Required permission: view workspace
{
"_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."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: logged in
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
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."
}
}
}
List types available in a workspace
This endpoint lists the types that are available in a given workspace.
id
integer
required path
ID of the workspace whose types will be listed
Example:1
200
OK
{
"_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
}
Types_by_WorkspaceModel{
"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 types collection\n\n**Resource**: TypesCollection",
"readOnly": true
}
]
}
}
},
"_embedded": {
"type": "object",
"properties": {
"elements": {
"type": "array",
"readOnly": true,
"items": {
"allOf": [
{
"$ref": "#/components/schemas/TypeModel"
},
{
"description": "Collection of Types"
}
]
}
}
}
}
}
}
]
}
404
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.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified workspace does not exist."
}
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."
}
}
}
