OpenProject

OpenProject Workspaces API

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: * [Portfolio](https://www.openproject.org/docs/api/endpoints/portfolios) * [Program](https://www.openproject.org/docs/api/endpoints/programs) * [Project](https://www.openproject.org/docs/api/endpoints/projects) A lot of resources reference the workspaces they are valid in, e.g. [Work package](https://www.openproject.org/docs/api/endpoints/work-packages/#linked-properties) and [Memberships](https://www.openproject.org/docs/api/endpoints/memberships/#linked-properties). 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.

GitHub OpenAPI

Operations 4

DELETE /api/v3/workspaces/{id}/favorite Unfavorite Workspace #
POST /api/v3/workspaces/{id}/favorite Favorite Workspace #
GET /api/v3/workspaces/{id}/types List types available in a workspace #
GET /api/v3/workspaces/schema View workspace schema #

Documentation

📖
Documentation
https://www.openproject.org/docs/api/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/openproject/refs/heads/main/openapi/openproject-workspaces-api-openapi.yml

Other Resources

🔗
Introduction
https://www.openproject.org/docs/api/introduction/
🔗
Endpoints
https://www.openproject.org/docs/api/endpoints/
🔗
GitHub
https://github.com/opf/openproject

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/openproject-workspaces-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openproject-workspaces-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  description: You're looking at the current **stable** documentation of the OpenProject APIv3.
  title: OpenProject API V3 (Stable) Workspaces 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: Workspaces
  description: Workspaces are containers for resources to be worked on and people with sets of permissions that work on the former.
paths:
  /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
      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
      description: Adds the workspace to the current user's favorites.
      operationId: Favorite_Workspace
      summary: Favorite Workspace
  /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:
      - 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/schema:
    get:
      responses:
        '200':
          content:
            application/hal+json:
              examples:
                response:
                  value:
                    _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
              schema:
                $ref: '#/components/schemas/Workspaces_schemaModel'
          description: OK
          headers: {}
      tags:
      - Workspaces
      description: ''
      operationId: View_workspace_schema
      summary: View workspace schema
components:
  schemas:
    CollectionLinks:
      type: object
      required:
      - self
      properties:
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
          - description: 'This collection resource.


              **Resource**: Collection'
    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
    TypeModel:
      type: object
      required:
      - id
      - name
      - color
      - position
      - isDefault
      - isMilestone
      - createdAt
      - updatedAt
      properties:
        id:
          type: integer
          description: Type id
          readOnly: true
          exclusiveMinimum: 0
        name:
          type: string
          description: Type name
          readOnly: true
        color:
          type:
          - string
          - 'null'
          description: The color used to represent this type
          readOnly: true
        position:
          type: integer
          description: Sort index of the type
          readOnly: true
        isDefault:
          type: boolean
          description: Is this type active by default in new projects?
          readOnly: true
        isMilestone:
          type: boolean
          description: Do work packages of this type represent a milestone?
          readOnly: true
        createdAt:
          type: string
          format: date-time
          description: Time of creation
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          description: Time of the most recent change to the user
        _links:
          type: object
          required:
          - self
          properties:
            self:
              allOf:
              - $ref: '#/components/schemas/Link'
              - description: 'This type


                  **Resource**: Type'
                readOnly: true
      example:
        _links:
          self:
            href: /api/v3/types/1
        _type: Type
        id: 1
        name: Bug
        color: '#ff0000'
        position: 1
        isDefault: true
        isMilestone: false
        createdAt: '2014-05-21T08:51:20.624Z'
        updatedAt: '2014-05-21T08:51:20.624Z'
    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.

                  Only 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
      patternProperties:
        ^customField\d+$:
          $ref: '#/components/schemas/SchemaPropertyModel'
        ^customComment\d+$:
          $ref: '#/components/schemas/SchemaPropertyModel'
      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
        customComment35:
          type: String
          name: Text project custom field comment
          required: false
          hasDefault: false
          writable: true
        _links:
          self:
            href: /api/v3/workspaces/schema
    SchemaPropertyModel:
      type: object
      required:
      - type
      - name
      - required
      - hasDefault
      - writable
      properties:
        type:
          type: string
          description: The resource type for this property.
        name:
          type: string
          description: The name of the property.
        required:
          type: boolean
          description: Indicates, if the property is required for submitting a request of this schema.
        hasDefault:
          type: boolean
          description: Indicates, if the property has a default.
        writable:
          type: boolean
          description: Indicates, if the property is writable when sending a request of this schema.
        options:
          type: object
          description: Additional options for the property.
        location:
          type: string
          description: Defines the json path where the property is located in the payload.
          default: ''
        placeholder:
          type: string
          description: A placeholder for the property to display if the property has no value.
        _links:
          type: object
          description: Useful links for this property (e.g. an endpoint to fetch allowed values)
    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.
    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


                    **Resource**: TypesCollection'
                  readOnly: true
          _embedded:
            type: object
            properties:
              elements:
                type: array
                readOnly: true
                items:
                  allOf:
                  - $ref: '#/components/schemas/TypeModel'
                  - description: Collection of Types
    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'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic