General 

This is the current DRAFT of the specification for OpenProject APIv3.

Please note that everything in this document might be subject to change in a future version of OpenProject. We intend to keep this specification as accurate as possible, however as long as the APIv3 is not in a stable state it is possible that there are intermediary differences between this specification and the real implementation. While we try to only specify what we want to keep, it might also happen that parts of this specification will be replaced incompatibly until the APIv3 is considered stable.

Hypermedia

TODO: Description & Resources

Formats

TODO: Description and why only JSON

HAL+JSON

HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API. Read more: http://stateless.co/hal_specification.html

OpenProject API implementation of HAL+JSON format enriches JSON and introduces a few meta properties:

  • _type - specifies the type of the resource (e.g.: WorkPackage, Project)
    • _links - contains all links available for the resource
    • _embedded - contains all embedded objects

HAL does not guarantee that embedded resources are embedded in their full representation, they might as well be partially represented (e.g. some properties can be left out). However in this API you have the guarantee that whenever a resource is embedded, it is embedded in its full representation.

API response structure

All API responses contain a single HAL+JSON object, even collections of objects are technically represented by a single HAL+JSON object that itself contains its members. More details on collections can be found in the Collections Section.

Authentication

For now the API only supports two authentication schemes: session based authentication and basic auth. Depending on the settings of the OpenProject instance many resources can be accessed without being authenticated. In case the instance requires authentication on all requests the client will receive an HTTP 401 status code in response to any request. Otherwise unauthenticated clients have all the permissions of the anonymous user.

Session-based Authentication

This means you have to login to OpenProject via the Web-Interface to be authenticated in the API. This method is well-suited for clients acting within the browser, like the Angular-Client built into OpenProject.

API Key through Basic Auth

Users can authenticate towards the API v3 using basic auth with ‘apikey’ as the user name and their API key as the password. Users can find their API key on their account page.

Example:

API_KEY=2519132cdf62dcf5a66fd96394672079f9e9cad1
curl -u apikey:$API_KEY https://community.openproject.com/api/v3/users/42

Why not username and password?

The simplest way to do basic auth would be to use a user’s username and password naturally. However, OpenProject already has supported API keys in the past for the API v2, though not through basic auth.

Using username and password directly would have some advantages:

  • It is intuitive for the user who then just has to provide those just as they would when logging into OpenProject.

  • No extra logic for token managment necessary.

On the other hand using API keys has some advantages too, which is why we went for that:

  • If compromised while saved on an insecure client the user only has to regenerate the API key instead of changing their password, too.

  • They are naturally long and random which makes them invulnerable to dictionary attacks and harder to crack in general.

Most importantly users may not actually have a password to begin with. Specifically when they have registered through an OpenID Connect provider.

Future Work

For the future we plan to add authentication modes based on OAuth2 and OpenID Connect.

Allowed HTTP methods

  • GET - Get a single resource or collection of resources

  • POST - Create a new resource or perform

  • PATCH - Update a resource

  • DELETE - Delete a resource

Compression

Responses are compressed if requested by the client. Currently gzip and deflate are supported. The client signals the desired compression by setting the Accept-Encoding header. If no Accept-Encoding header is send, Accept-Encoding: identity is assumed which will result in the API responding uncompressed.

Basic Objects 

Links

Links to other resources in the API are represented uniformly by so called link objects.

Local Properties

PropertyDescriptionTypeRequiredNullableDefault
hrefURL to the referenced resource (might be relative)String
titleRepresentative label for the resourceString
templatedIf true the href contains parts that need to be replaced by the clientBooleanfalse
methodThe HTTP verb to use when requesting the resourceStringGET
payloadThe payload to send in the request to achieve the desired resultStringunspecified

All link objects must contain the href property, though it might be null. Thus the following is a valid link object:

{ “href”: null }

whereas { } is not a valid link object. The meaning of "href": null is that no resource is referenced. For example a work package without an assignee will still have an assignee link, but its href will be null.

If a title is present, the client can display the title to the user when referring to the resource.

Templated links are links that contain client replaceable parts. Replaceable parts are enclosed in braces. For example the link api/v3/example/{id} is not complete in itself, but the client needs to replace the string {id} itself. As of now the API does not indicate the valid replacement values.

The method indicates which HTTP verb the client must use when following the link for the intended purpose.

If a payload is specified, it needs to be sent as the body of the request to achieve the desired result (e.g. perform the action represented by the link). If no payload is specified, there is either no payload to send or a valid payload is not specified by the link object. A payload might also be templated slightly. If the templated property is true, a payload might contain replaceable parts in its strings (e.g. { "href": "/api/v3/examples/{example_id}" }).

Note: When writing links (e.g. during a PATCH operation) only changes to href are accepted. Changes to all other properties will be silently ignored.

Errors

In case of an error, the API will respond with an apropriate HTTP status code. For responses with an HTTP status of 4xx and 5xx the body will always contain a single error object. Error objects shall give the client additional details about the cause of an errorneous response.

General errors

  • Error objects have their _type set to Error

  • The errorIdentifier serves as a unique (and machine readable) identifier for a specific error cause

    • There may be multiple possible error identifiers per HTTP status code
    • There may be multiple possible HTTP status codes per error identifier
    • The “List of Error Identifiers” defines the possible mappings between HTTP status and error identifier
  • The message contains a human readable concise message describing the error

    • It optionally includes specific information, for example which permission would have been needed to perform an action
    • It is localized depending on the users preferences
    • It must not include HTML or other kind of markup
    • Error messages form complete sentences including punctuation

Example

{ “_type”: “Error”, “errorIdentifier”: “urn:openproject-org:api:v3:errors:InternalServerError”, “message”: “An internal server error occured. This is not your fault.” }

Embedded error information

Errors might optionally contain embedded objects that contain further information.

Error details

Under the embedded key details there might be an object describing the error more verbosely. For example if the error affects a specific field, this field could be defined there.

Example

{ “_type”: “Error”, “errorIdentifier”: “urn:openproject-org:api:v3:examples:ExampleError”, “message”: “This is an example error.”, “_embedded”: { “details”: { “_type”: “ExampleErrorDetailInformation”, “errorneousField”: “subject” } } }

Multiple error objects

To ease implementation of basic clients it is guaranteed that the response body always only contains a single error object. However it is allowed that an error object embeds other error objects under the key errors, thereby aggregating them.

The errorIdentifier of such an object is always urn:openproject-org:api:v3:errors:MultipleErrors. The message can either describe one of the embedded errors or simply state that multiple errors occured.

Example

{ “_type”: “Error”, “errorIdentifier”: “urn:openproject-org:api:v3:errors:MultipleErrors”, “message”: “Multiple fields violated their constraints.”, “_embedded”: { “errors”: [ { “_type”: “Error”, “errorIdentifier”: “urn:openproject-org:api:v3:errors:PropertyConstraintViolation”, “…”: “…” }, { “_type”: “Error”, “errorIdentifier”: “urn:openproject-org:api:v3:errors:PropertyConstraintViolation”, “…”: “…” } ] } }

List of Error Identifiers

  • urn:openproject-org:api:v3:errors:InvalidQuery (HTTP 400) - The query contained a value that did not match the servers expectation

  • urn:openproject-org:api:v3:errors:InvalidRequestBody (HTTP 400) - The format of the request body did not match the servers expectation

  • urn:openproject-org:api:v3:errors:InvalidRenderContext (HTTP 400) - The client specified a rendering context that does not exist

  • urn:openproject-org:api:v3:errors:InvalidUserStatusTransition (HTTP 400) - The client used an invalid transition in the attempt to change the status of a user account.

  • urn:openproject-org:api:v3:errors:Unauthenticated (HTTP 401) - The client has to authenticate to access the requested resource.

  • urn:openproject-org:api:v3:errors:MissingPermission (HTTP 403) - The client does not have the needed permissions to perform the requested action

  • urn:openproject-org:api:v3:errors:NotFound (HTTP 404) - Default for HTTP 404 when no further information is available

  • urn:openproject-org:api:v3:errors:UpdateConflict (HTTP 409) - The resource changed between GET-ing it and performing an update on it

  • urn:openproject-org:api:v3:errors:TypeNotSupported (HTTP 415) - The request contained data in an unsupported media type (Content-Type)

  • urn:openproject-org:api:v3:errors:PropertyIsReadOnly (HTTP 422) - The client tried to set or change a property that is not writable

  • urn:openproject-org:api:v3:errors:PropertyConstraintViolation (HTTP 422) - The client tried to set a property to an invalid value

  • urn:openproject-org:api:v3:errors:PropertyValueNotAvailableAnymore (HTTP 422) - An unchanged property needs to be changed, because other changes to the resource make it unavailable

  • urn:openproject-org:api:v3:errors:ResourceTypeMismatch (HTTP 422) - A link to a resource of a specific type was expected, but the link to another type of resource was provided

  • urn:openproject-org:api:v3:errors:PropertyFormatError (HTTP 422) - A property value was provided in a format that the server does not understand or accept

  • urn:openproject-org:api:v3:errors:InternalServerError (HTTP 500) - Default for HTTP 500 when no further information is available

  • urn:openproject-org:api:v3:errors:MultipleErrors - Multiple errors occured. See the embedded errors array for more details.

Formattable Text

OpenProject supports text formatting in Textile. Other text formats may be introduced in the future. Properties that contain formattable text have a special representation in this API. In this specification their type is indicated as Formattable. Their representation contains the following properties:

PropertyDescriptionTypeExampleSupported operations
formatIndicates the formatting language of the raw textStringtextileREAD
rawThe raw text, as entered by the userStringI *am* formatted!READ / WRITE
htmlThe text converted to HTML according to the formatStringI <strong>am</strong> formatted!READ

format can as of today have one of the following values:

  • plain - only basic formatting, e.g. inserting paragraphs and line breaks into HTML

  • textile - formatting using Textile

  • custom - There is no apparent formatting rule that transforms the raw version to HTML (only used for read only properties)

More formats might be added in the future.

Note that raw is the only property supporting the write operation. A property of type Formattable that is marked as read and write, will only accept changes to the raw property. Changes to format and html will be silently ignored. It is thus sufficient to solely provide the raw property for changes.

If the Formattable is marked as read only, the raw attribute also becomes read only.

Example

{ “format”: “textile”, “raw”: “I am formatted!”, “html”: “I am formatted!” }

Dates, Times and Durations

Representation of time related values in this API is done according to ISO 8601. In this specification the following terms will be used as type specifiers (e.g. in tables):

  • Date - refers to an ISO 8601 date, e.g. “2014-05-21”

  • DateTime - refers to an ISO 8601 combined date and time, e.g. “2014-05-21T13:37:00Z”

  • Duration - refers to an ISO 8601 duration, e.g. “P1DT18H”

Colors

Colors are represented in RGB using hexadecimal notation as specified in CSS Color Module Level 3. That is a # followed by either three or six hexadecimal digits.

Examples

red: #ff0000 or #f00 green: #00ff00 or #0f0 black: #000000 or #000 white: #ffffff or #fff

Digests

Digests (or Hashes) are one way functions that map data of arbitrary size to data of a fixed size. In OpenProject they are for example used to calculate checksums for (attachment) files. The checksum calculated depends on the hashed data and the algorithm used as hash function.

Therefore all digests are represented in the following form:

PropertyDescriptionTypeExample
algorithmThe algorithm used to compute the digestStringmd5
hashThe calculated digest in hexadecimal notationString64c26a8403cd796ea4cf913cda2ee4a9

Example

{ “algorithm”: “md5”, “hash”: “64c26a8403cd796ea4cf913cda2ee4a9” }

Collections 

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. An explanation of offset and cursor based pagination can be found below the links table.

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

PropertyDescriptionTypeAvailability
totalThe total amount of elements available in the collectionIntegeralways
pageSizeAmount of elements that a response will holdIntegerwhen paginated
countActual amount of elements in this responseIntegeralways
offsetThe page number that is requested from paginated collectionIntegerwhen offset based available
groupsSummarized information about aggregation groupsObjectwhen grouping
totalSumsAggregations of supported values for elements of the collectionObjectwhen showing sums
LinkDescriptionAvailability
selfLink to the current page in the collectionalways
changeSizeTemplated link to change the page size, might change relative positionwhen paginated
jumpToTemplated link to jump to a specified offsetwhen offset based available
nextByOffsetLink to retrieve the following page of elements (offset based)when offset based available
previousByOffsetLink to retrieve the preceding page of elements (offset based)when offset based available
nextByCursorLink to retrieve the elements following the current page (cursor based)when cursor based available
previousByCursorLink to retrieve the elements preceding the current page (cursor based)when cursor based available

Offset based pagination 

Offset based pagination works by specifying two values: the offset and the pageSize. The page size determines how many items there will be in a single response at most. The offset determines which page is returned as response, with 1 being the first page (one-indexed). Note that the server might not allow arbitrarily large page sizes, a client should therefore always check the page size accepted by the server using the pageSize property of the response.

The benefit of offset based pagination is that the total number of pages can be easily determined and that it is possible to jump to arbitrary pages within the collection. Offset based pagination is therefore well suited when a result is displayed to the end user in the form of multiple pages anyway.

A drawback of offset based pagination comes with concurrent modification of the collection. If the collection is modified between two page requests, it is possible that the client receives elements close to the page boundaries twice or does not see them at all.

view offset based
/api/v3/examples{?offset,pageSize}
  • Parameters
  • offset
    integer (optional) Default: 1 Example: 25

    Page number inside the requested collection.

    pageSize
    integer (optional) Example: 25

    Number of elements to display per page.

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/examples?offset=25&pageSize=25"
        },
        "jumpTo": {
          "href": "/api/v3/examples?offset={offset}&pageSize=25",
          "templated": true
        },
        "changeSize": {
          "href": "/api/v3/examples?offset=25&pageSize={size}",
          "templated": true
        },
        "previousByOffset": {
          "href": "/api/v3/examples?offset=0&pageSize=25"
        },
        "previousByCursor": {
          "href": "/api/v3/examples?before=bar&pageSize=25"
        }
      },
      "_type": "Collection",
      "total": 27,
      "pageSize": 25,
      "count": 2,
      "offset": 25,
      "_embedded": {
        "elements": [
          {
            "foo": "bar"
          },
          {
            "foo": "baz"
          }
        ]
      }
    }

Cursor based pagination 

Cursor based pagination is intended to be used, when the client needs a consistent and complete (sub-) range of the collection, e.g. in infinite scrolling scenarios. In cursor based pagination the client will receive a link to the next and the previous page in the result set. The guarantee is, that the boundaries of that page will align with the boundaries of the current page, regardless of changes to the collection.

The drawback for cursor based pagination is, that it is not immediately determinable how many “next” and how many “previous” pages there are. Cursor based pagination is therefore less suited for use cases where you want to directly “jump” to an arbitrary page.

view cursor based
/api/v3/examples{?before,after,pageSize}
  • Parameters
  • before
    string (optional) Example: bar

    Display the elements preceding the given element. Note that the value of this parameter is very specific to the collection, a client should not try to infer values, but use the previous link offered by the collection.

    after
    string (optional) Example: buz

    Display the elements succeeding the given element. Note that the value of this parameter is very specific to the collection, a client should not try to infer values, but use the next link offered by the collection.

    pageSize
    integer (optional) Example: 25

    Number of elements to display per page.

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/examples?after=buz&pageSize=25"
        },
        "changeSize": {
          "href": "/api/v3/examples?after=buz&pageSize={size}",
          "templated": true
        },
        "previousByCursor": {
          "href": "/api/v3/examples?before=bar&pageSize=25"
        }
      },
      "_type": "Collection",
      "total": 27,
      "pageSize": 25,
      "count": 2,
      "_embedded": {
        "elements": [
          {
            "foo": "bar"
          },
          {
            "foo": "baz"
          }
        ]
      }
    }

Aggregations 

Collections may support different kinds of aggregations. Some properties can be summed up. If requested the collection will include the totalSums property, which is a dictionary, where the keys represent the names of the summed properties and the values represent their sums. Note that you have to mark a column as summable in the instance settings, to be able to retrieve its sums.

It is also possible to group the contents of a collection. In this case:

  • the elements will be ordered by the specified group key (so that the client receives one group after another)

  • The groups property will contain a collection of group objects

A group object contains aggregation data for the elements of a group:

Local Properties

PropertyDescriptionTypeAvailability
valueThe value to which the group belongs (e.g. the Status’ name)Stringalways
countActual amount of elements in this responseIntegeralways
sumsA dictionary with property sums inside this group (see totalSums)Dictionarywhen sums requested
LinkDescriptionAvailability
valueLinkLink to the corresponding grouping object (e.g. the Status)only if grouping by a linkable object

Note that you will always receive a value, but only receive a valueLink if the grouping was performed on a linkable property.

view aggregated result
/api/v3/examples{?groupBy,showSums}
  • Parameters
  • groupBy
    string (optional) Example: status

    The column to group by. Note: Aggregation is as of now only supported by the work package collection. You can pass any column name as returned by the queries endpoint.

    showSums
     (optional) Default: false 
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
        "_links": {
            "self": { "href": "/api/v3/examples?groupBy=foo&showSums=true" },
            "changeSize": {
                "href": "/api/v3/examples?after=buz&pageSize={size}",
                "templated": true
            }
        },
        "_type": "Collection",
        "total": 5,
        "pageSize": 25,
        "count": 5,
        "_embedded": {
            "elements": [
                { "foo": "bar", "i": 1 },
                { "foo": "bar", "i": 2 },
                { "foo": "bar", "i": 3 },
                { "foo": "baz", "i": 4 },
                { "foo": "baz", "i": 5 }
            ],
            "groups": [
                {
                    "value : "bar",
                    "count": 3,
                    "sums": {
                        "i": 6
                    }
                },
                {
                    "value : "baz",
                    "count": 2,
                    "sums": {
                        "i": 9
                    }
                }
            ],
            "totalSums": {
                "i": 15
            }
        }
    }

Activities 

Local Properties

PropertyDescriptionTypeConstraintsSupported operations
idActivity idIntegerx > 0READ
versionActivity versionIntegerx > 0READ
commentFormattableREAD / WRITE
detailsArray of FormattableREAD
createdAtTime of creationDateTimeREAD

Activity can be either _type Activity or _type Activity::Comment.

Activity 

View activity
/api/v3/activities/{id}
  • Parameters
  • id
    integer (required) Example: 1

    Activity id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Activity::Comment",
      "_links": {
        "self": {
          "href": "/api/v3/activity/1",
          "title": "Priority changed from High to Low"
        },
        "workPackage": {
          "href": "/api/v3/work_packages/1",
          "title": "quis numquam qui voluptatum quia praesentium blanditiis nisi"
        },
        "user": {
          "href": "/api/v3/users/1",
          "title": "John Sheppard - admin"
        }
      },
      "id": 1,
      "details": [
        {
          "format": "textile",
          "raw": "Lorem ipsum dolor sit amet.",
          "html": "<p>Lorem ipsum dolor sit amet.</p>"
        }
      ],
      "comment": {
        "format": "textile",
        "raw": "Lorem ipsum dolor sit amet.",
        "html": "<p>Lorem ipsum dolor sit amet.</p>"
      },
      "createdAt": "2014-05-21T08:51:20Z",
      "version": 31
    }
Update activity
/api/v3/activities/{id}

Updates an activity’s comment and, on success, returns the updated activity.

  • Parameters
  • id
    integer (required) Example: 1

    Activity id

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
      "comment": {
        "raw": "The updated comment"
      }
    }
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Activity::Comment",
      "_links": {
        "self": {
          "href": "/api/v3/activity/1",
          "title": "Priority changed from High to Low"
        },
        "workPackage": {
          "href": "/api/v3/work_packages/1",
          "title": "quis numquam qui voluptatum quia praesentium blanditiis nisi"
        },
        "user": {
          "href": "/api/v3/users/1",
          "title": "John Sheppard - admin"
        }
      },
      "id": 1,
      "details": [
        {
          "format": "textile",
          "raw": "Lorem ipsum dolor sit amet.",
          "html": "<p>Lorem ipsum dolor sit amet.</p>"
        }
      ],
      "comment": {
        "format": "textile",
        "raw": "Lorem ipsum dolor sit amet.",
        "html": "<p>Lorem ipsum dolor sit amet.</p>"
      },
      "createdAt": "2014-05-21T08:51:20Z",
      "version": 31
    }
  • Response  400
  • Occurs when the client did not send a valid JSON object in the request body.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
      "message": "The request body was not a single JSON object."
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: edit journals

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to edit the comment of this journal entry."
    }
  • Response  422
  • Returned if the client tries to modify a read-only property.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyIsReadOnly",
      "message": "The ID of an activity can't be changed."
    }

Attachments 

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

LinkDescriptionCondition
deleteDeletes this attachment Permission: edit on attachment container

Linked Properties

LinkDescriptionTypeConstraintsSupported operations
selfThis attachmentAttachmentnot nullREAD
containerThe object (e.g. WorkPackage) housing the attachmentAnythingnot nullREAD
authorThe user who uploaded the attachmentUsernot nullREAD
downloadLocationDirect download link to the attachment-not nullREAD

Local Properties

PropertyDescriptionTypeConstraintsSupported operations
idAttachment’s idIntegerx > 0READ
fileNameThe name of the uploaded fileStringnot nullREAD
fileSizeThe size of the uploaded file in BytesIntegerx >= 0READ
descriptionA user provided description of the fileFormattablenot nullREAD
contentTypeThe files MIME-Type as determined by the serverStringnot nullREAD
digestA checksum for the files contentDigestnot nullREAD
createdAtTime of creationDateTimenot nullREAD

Attachment 

View attachment
/api/v3/attachments/{id}
  • Parameters
  • id
    integer (required) Example: 1

    Attachment id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
        "_type": "Attachment",
        "_links": {
            "self": {
                "href": "/api/v3/attachments/1"
            },
            "container" {
                "href": "/api/v3/work_packages/1"
            },
            "author": {
                "href": "/api/v3/users/1"
            },
            "downloadLocation": {
                "href": "/attachments/1/download"
            }
        },
        "id": 1,
        "fileName": "cat.png",
        "filesize": 24,
        "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",
            "64c26a8403cd796ea4cf913cda2ee4a9":
        },
        "createdAt": "2014-05-21T08:51:20Z"
    }
  • Response  404
  • Returned if the attachment does not exist or the client does not have sufficient permissions to see it.

    Required permission: view permission for the container of the attachment

    Note: A client without sufficient permissions shall not be able to test for the existence of an attachment. That’s why a 404 is returned here, even if a 403 might be more appropriate.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified attachment does not exist."
    }
Delete attachment
/api/v3/attachments/{id}

Permanently deletes the specified attachment.

  • Parameters
  • id
    integer (required) Example: 1

    Attachment id

  • Response  204
  • Returned if the attachment was deleted successfully.

    Note that the response body is empty as of now. In future versions of the API a body might be returned along with an appropriate HTTP status.

  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: edit permission for the container of the attachment

    Note that you will only receive this error, if you are at least allowed to see the attachment.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to delete this attachment."
    }
  • Response  404
  • Returned if the attachment does not exist or the client does not have sufficient permissions to see it.

    Required permission: view permission for the container of the attachment

    Note: A client without sufficient permissions shall not be able to test for the existence of an attachment. That’s why a 404 is returned here, even if a 403 might be more appropriate.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified attachment does not exist."
    }

Attachments by work package 

List attachments
/api/v3/work_packages/{id}/attachments
  • Parameters
  • id
    integer (required) Example: 1

    ID of the work package whose attachments will be listed

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
        "_links": {
            "self": { "href": "/api/v3/work_packages/1/attachments" }
        },
        "total": 2,
        "count": 2,
        "_type": "Collection",
        "_embedded":
        {
            "elements": [
                {
                    "_type": "Attachment",
                    "_links": {
                        "self": {
                            "href": "/api/v3/attachments/1"
                        },
                        "container" {
                            "href": "/api/v3/work_packages/1"
                        },
                        "author": {
                            "href": "/api/v3/users/1"
                        },
                        "downloadLocation": {
                            "href": "/attachments/1/download"
                        }
                    },
                    "id": 1,
                    "fileName": "cat.png",
                    "filesize": 24,
                    "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",
                        "64c26a8403cd796ea4cf913cda2ee4a9":
                    },
                    "createdAt": "2014-05-21T08:51:20Z"
                },
                {
                    "_type": "Attachment",
                    "_links": {
                        "self": {
                            "href": "/api/v3/attachments/2"
                        },
                        "container" {
                            "href": "/api/v3/work_packages/1"
                        },
                        "author": {
                            "href": "/api/v3/users/1"
                        },
                        "downloadLocation": {
                            "href": "/attachments/2/download"
                        }
                    },
                    "id": 2,
                    "fileName": "cat2.png",
                    "filesize": 24,
                    "description": {
                        "format": "plain",
                        "raw": "A picture of another cute cat",
                        "html": "<p>A picture of another cute cat</p>"
                    },
                    "contentType": "image/png",
                    "digest": {
                        "algorithm": "md5",
                        "46c26a8403cd769ea4c9f13cdae2e49a":
                    },
                    "createdAt": "2014-05-21T08:51:20Z"
                }
            ]
        }
    }
  • Response  404
  • Returned if the work package does not exist or the client does not have sufficient permissions to see it.

    Required permission: view work package

    Note: A client without sufficient permissions shall not be able to test for the existence of a work package. That’s why a 404 is returned here, even if a 403 might be more appropriate.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified work package does not exist."
    }
Add attachment
/api/v3/work_packages/{id}/attachments

To add an attachment to a work package, a client needs to issue a request of type multipart/form-data with exactly two parts.

The first part must be called metadata. Its content type is expected to be application/json, the body must be a single JSON object, containing at least the fileName and optionally the attachments description.

The second part must be called file, its content type should match the mime type of the file. The body must be the raw content of the file. Note that a filename must be indicated in the Content-Disposition of this part, however it will be ignored. Instead the fileName inside the JSON of the metadata part will be used.

  • Parameters
  • id
    integer (required) Example: 1

    ID of the work package to receive the attachment

  • Request
  • Headers
    Content-Type: multipart/form-data
    Body
    --boundary-delimiter
    Content-Disposition: form-data; name="metadata"
    Content-Type: application/json; charset=UTF-8
    
    {
      "fileName": "cute-cat.png",
      "description": {
        "raw": "A cute kitty, cuddling with its friends!"
      }
    }
    
    --boundary-delimiter
    Content-Disposition: form-data; name="file"; filename="attachment"
    Content-Type: image/png
    
    PNG file data
    --boundary-delimiter--
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
        "_type": "Attachment",
        "_links": {
            "self": {
                "href": "/api/v3/attachments/1"
            },
            "container" {
                "href": "/api/v3/work_packages/1"
            },
            "author": {
                "href": "/api/v3/users/1"
            },
            "downloadLocation": {
                "href": "/attachments/1/download"
            }
        },
        "id": 1,
        "fileName": "cat.png",
        "filesize": 24,
        "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",
            "64c26a8403cd796ea4cf913cda2ee4a9":
        },
        "createdAt": "2014-05-21T08:51:20Z"
    }
  • Response  400
  • Returned if the client sends a not understandable request. Reasons include:

    • Omitting one of the required parts (metadata and file)

    • sending unparsable JSON in the metadata part

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
      "message": "The request could not be parsed as JSON."
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: edit work package or add work package

    Note that you will only receive this error, if you are at least allowed to see the work package.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to delete this attachment."
    }
  • Response  404
  • Returned if the work package does not exist or the client does not have sufficient permissions to see it.

    Required permission: view work package

    Note: A client without sufficient permissions shall not be able to test for the existence of a work package. That’s why a 404 is returned here, even if a 403 might be more appropriate.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified work package does not exist."
    }
  • Response  422
  • Returned if the client tries to send an invalid attachment. Reasons are:

    • Omitting the file name (fileName property of metadata part)

    • Sending a file that is too large

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
      "message": "File is too large (maximum size is 5242880 Bytes)."
    }

Categories 

Linked Properties

LinkDescriptionTypeConstraintsSupported operations
selfThis categoryCategorynot nullREAD
projectThe project of this categoryProjectnot nullREAD
defaultAssigneeDefault assignee for work packages of this categoryUserREAD

Local Properties

PropertyDescriptionTypeConstraintsSupported operations
idCategory idIntegerx > 0READ
nameCategory nameStringREAD

Categories by Project 

List categories of a project
/api/v3/projects/{project_id}/categories
  • Parameters
  • project_id
    integer (required) Example: 1

    ID of the project whoose categories will be listed

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/projects/11/categories"
        }
      },
      "total": 2,
      "count": 2,
      "_type": "Collection",
      "_embedded": {
        "elements": [
          {
            "_links": {
              "self": {
                "href": "/api/v3/categories/10",
                "title": "Category with assignee"
              },
              "project": {
                "href": "/api/v3/projects/11",
                "title": "Example project"
              },
              "defaultAssignee": {
                "href": "/api/v3/users/42",
                "title": "John Sheppard"
              }
            },
            "_type": "Category",
            "id": 10,
            "name": "Foo"
          },
          {
            "_links": {
              "self": {
                "href": "/api/v3/categories/11"
              },
              "project": {
                "href": "/api/v3/projects/11"
              }
            },
            "_type": "Category",
            "id": 11,
            "name": "Bar"
          }
        ]
      }
    }
  • Response  404
  • Returned if the project does not exist or the client does not have sufficient permissions to see it.

    Required permission: view project

    Note: A client without sufficient permissions shall not be able to test for the existence of a project. That’s why a 404 is returned here, even if a 403 might be more appropriate.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified project does not exist."
    }

Category 

View Category
/api/v3/categories/{id}
  • Parameters
  • id
    integer (required) Example: 1

    category id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/categories/10",
          "title": "Category with assignee"
        },
        "project": {
          "href": "/api/v3/projects/11",
          "title": "Example project"
        },
        "defaultAssignee": {
          "href": "/api/v3/users/42",
          "title": "John Sheppard"
        }
      },
      "_type": "Category",
      "id": 10,
      "name": "Foo"
    }
  • Response  404
  • Returned if the category does not exist or the client does not have sufficient permissions to see it.

    Required permission: view project (defining the category)

    Note: A client without sufficient permissions shall not be able to test for the existence of a category. That’s why a 404 is returned here, even if a 403 might be more appropriate.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified category does not exist."
    }

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 you can find in your settings.yml.

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

LinkDescriptionTypeNullableSupported operations
selfThe configurationConfigurationREAD

Local Properties

PropertyDescriptionTypeConditionSupported operations
maximumAttachmentFileSizeThe maximum allowed size of an attachment in BytesIntegerREAD
perPageOptionsPage size steps to be offered in paginated list UIInteger[]READ

Configuration 

View configuration
/api/v3/configuration
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Configuration",
      "_links": {
        "href": "/api/v3/configuration"
      },
      "maximumAttachmentFileSize": 5242880,
      "perPageOptions": [
        1,
        10,
        100
      ]
    }

Forms 

This API provides forms as a concept to aid in editing or creating resources. The goal of forms is to:

  • make writable properties of a resource discoverable

  • show to which values a property can be set

  • validate changes to a resource and indicate validation errors

These benefits aside, a client can freely choose to immediately edit a resource without prior validation by a form. In the case of an invalid request the edit will fail and return appropriate errors nevertheless.

A form is associated to a single resource and aids in performing changes on that resource. When posting to a form endpoint with an empty request body or an empty JSON object, you will receive an initial form for the associated resource. Subsequent calls to the form should contain a single JSON object as described by the form.

Actions

LinkDescriptionCondition
validateValidate changes, show errors and allowed values for changed resource
commitActually perform changes to the resourceform content is valid
previewMarkupPost markup (e.g. textile) here to receive an HTML-rendered response

Linked Properties

LinkDescriptionTypeNullableSupported operations
selfThis formFormREAD

Embedded Properties:

Apart from the linked properties, forms contain always three other embedded properties:

  • payload

  • schema

  • validationErrors

Their purpose is explained below.

Payload

The payload contains an edited version of the resource that will be modified when commiting the form. This representation contains all writable properties of the resource and reflects all changes that the latest call to validate included, thereby acting as a preview for the changes.

In case the client tries to set the value to something invalid, the invalid change is also reflected here. However a validation error (see below) indicates that a commit of this payload would fail.

It might happen that setting one property affects the allowed values for another property. Thus by changing a property A the current value of another property B might become invalid. If the client did not yet touch the value of B, the payload will contain a default value for that property. Nevertheless the client will also receive an apropriate validation error for value B.

The content of this element can be used as a template for the request body of a call to validate or commit.

A call to validate and commit does not need to include all properties that were defined in the payload section. It is only necessary to include the properties that you want to change, as well as the lockVersion if one is present. However you may include all the properties sent in the payload section.

Schema

The schema embedded in a form is a normal schema describing the underlying resource. However, the embedded schema can change with each revalidation of the form. For example it might be possible, that changing the type of a work package affects its available properties, as well as possible values for certain properties. As this makes the embedded schema very dynamic, it is not included as a static link.

Validation Errors

Like a schema the validation errors build a dictionary where the key is a property name. Each value is an error object that indicates the error that occured validating the corresponding property. There are only key value pairs for properties that failed validation, the element is empty if all validations succeeded.

However note that even in the case of validation errors, the response you receive from the form endpoint will be an HTTP 200. That is because the main purpose of a form is helping the client to sort out validation errors.

Example Form 

show or validate form
/api/v3/example/form

This is an example of how a form might look like. Note that this endpoint does not exist in the actual implementation.

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
      "lockVersion": 5,
      "_type": "Example",
      "subject": "An example title"
    }
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/example/form"
        },
        "validate": {
          "href": "/api/v3/example/form",
          "method": "POST"
        },
        "previewMarkup": {
          "href": "/api/v3/render/textile",
          "method": "POST"
        },
        "commit": {
          "href": "/api/v3/example",
          "method": "PATCH"
        }
      },
      "_type": "Form",
      "_embedded": {
        "payload": {
          "_links": {
            "status": {
              "href": "/api/v3/statuses/1"
            }
          },
          "_type": "Example",
          "lockVersion": 5,
          "subject": "An example title"
        },
        "schema": {
          "_type": "Schema",
          "_links": {
            "self": {
              "href": "/api/v3/example/schema"
            }
          },
          "lockVersion": {
            "type": "Integer",
            "writable": false
          },
          "subject": {
            "type": "String",
            "minLength": 1,
            "maxLength": 255
          },
          "status": {
            "_links": {
              "allowedValues": [
                {
                  "href": "/api/v3/statuses/1",
                  "title": "New"
                },
                {
                  "href": "/api/v3/statuses/2",
                  "title": "Closed"
                }
              ]
            },
            "type": "Status",
            "_embedded": {
              "allowedValues": [
                {
                  "_links": {
                    "self": {
                      "href": "/api/v3/statuses/1"
                    }
                  },
                  "_type": "Status",
                  "id": 1,
                  "name": "New",
                  "position": 1,
                  "isDefault": true,
                  "isClosed": false,
                  "defaultDoneRatio": 0,
                  "createdAt": "2014-05-21T08:51:20Z",
                  "updatedAt": "2014-05-21T09:12:00Z"
                },
                {
                  "_links": {
                    "self": {
                      "href": "/api/v3/statuses/2"
                    }
                  },
                  "_type": "Status",
                  "id": 2,
                  "name": "Closed",
                  "position": 2,
                  "isDefault": false,
                  "isClosed": true,
                  "defaultDoneRatio": 100,
                  "createdAt": "2014-05-21T08:51:20Z",
                  "updatedAt": "2014-05-21T09:12:00Z"
                }
              ]
            }
          }
        },
        "validationErrors": {
          "subject": {
            "_type": "Error",
            "errorIdentifier": "urn:openproject-org:api:v3:errors:BadExampleError",
            "message": "For the purpose of this example we need a validation error. The remainder of the response pretends there were no errors."
          }
        }
      }
    }
  • Response  400
  • Occurs when the client did not send a valid JSON object in the request body and the request body was not empty.

    Note that this error only occurs when the content is not at all a single JSON object. It does not occur for requests containing undefined properties or invalid property values.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
      "message": "The request body was neither empty, nor did it contain a single JSON object."
    }
  • Response  403
  • Returned if the client does not have sufficient permissions to modify the associated resource.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to edit example resources."
    }
  • Response  409
  • Returned if underlying resource was changed since the client requested the form. This is determined using the lockVersion property.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:UpdateConflict",
      "message": "The resource you are about to edit was changed in the meantime."
    }

Priorities 

Linked Properties

LinkDescriptionTypeConstraintsSupported operations
selfThis priorityPrioritynot nullREAD

Local Properties

PropertyDescriptionTypeConstraintsSupported operations
idPriority idIntegerx > 0READ
namePriority nameStringnot emptyREAD
positionSort index of the priorityIntegerx > 0READ
isDefaultIndicates whether this is the default valueBooleanREAD
isActiveIndicates whether the priority is availableBooleanREAD

Priorities 

List all Priorities
/api/v3/priorities
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/priorities"
        }
      },
      "_type": "Collection",
      "total": 4,
      "count": 4,
      "_embedded": {
        "elements": [
          {
            "_type": "Priority",
            "_links": {
              "self": {
                "href": "/api/v3/priorities/1",
                "title": "Low"
              }
            },
            "id": 1,
            "name": "Low",
            "position": 1,
            "isDefault": false,
            "isActive": true
          },
          {
            "_type": "Priority",
            "_links": {
              "self": {
                "href": "/api/v3/priorities/2",
                "title": "Normal"
              }
            },
            "id": 2,
            "name": "Normal",
            "position": 2,
            "isDefault": true,
            "isActive": true
          },
          {
            "_type": "Priority",
            "_links": {
              "self": {
                "href": "/api/v3/priorities/3",
                "title": "High"
              }
            },
            "id": 3,
            "name": "High",
            "position": 3,
            "isDefault": false,
            "isActive": true
          },
          {
            "_type": "Priority",
            "_links": {
              "self": {
                "href": "/api/v3/priorities/4",
                "title": "Immediate"
              }
            },
            "id": 4,
            "name": "Immediate",
            "position": 5,
            "isDefault": false,
            "isActive": true
          }
        ]
      }
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: view work package (on any project)

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to see the priorities."
    }

Priority 

view Priority
/api/v3/priorities/{id}
  • Parameters
  • id
    integer (required) Example: 1

    Priority id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Priority",
      "_links": {
        "self": {
          "href": "/api/v3/priorities/1",
          "title": "Low"
        }
      },
      "id": 1,
      "name": "Low",
      "position": 1,
      "isDefault": false,
      "isActive": true
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: view work package (on any project)

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to see this priority."
    }

Projects 

Actions

LinkDescriptionCondition
createWorkPackageForm endpoint that aids in preparing and creating a work package Permission: add work packages
createWorkPackageImmediateDirectly creates a work package in the project Permission: add work packages

Linked Properties

LinkDescriptionTypeConstraintsSupported operations
selfThis projectProjectnot nullREAD
categoriesCategories available in this projectCollectionnot nullREAD
typesTypes available in this projectCollectionnot nullREAD
versionsVersions available in this projectCollectionnot nullREAD
workPackagesWork Packages of this projectCollectionnot nullREAD

Local Properties

PropertyDescriptionTypeConstraintsSupported operations
idProjects’s idIntegerx > 0READ
identifierStringREAD
nameStringREAD
descriptionStringREAD
createdAtTime of creationDateTimeREAD
updatedAtTime of the most recent change to the projectDateTimeREAD

Project 

View project
/api/v3/projects/{id}
  • Parameters
  • id
    integer (required) Example: 1

    Project id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Project",
      "_links": {
        "self": {
          "href": "/api/v3/projects/1",
          "title": "Lorem"
        },
        "createWorkPackage": {
          "href": "/api/v3/projects/1/work_packages/form",
          "method": "post"
        },
        "createWorkPackageImmediate": {
          "href": "/api/v3/projects/1/work_packages",
          "method": "post"
        },
        "categories": {
          "href": "/api/v3/projects/1/categories"
        },
        "types": {
          "href": "/api/v3/projects/1/types"
        },
        "versions": {
          "href": "/api/v3/projects/1/versions"
        },
        "workPackages": {
          "href": "/api/v3/projects/1/work_packages"
        }
      },
      "id": 1,
      "identifier": "project_identifier",
      "name": "Project example",
      "description": "Lorem ipsum dolor sit amet",
      "createdAt": "2014-05-21T08:51:20Z",
      "updatedAt": "2014-05-21T08:51:20Z"
    }
  • Response  404
  • Returned if the project does not exist or the client does not have sufficient permissions to see it.

    Required permission: view project

    Note: A client without sufficient permissions shall not be able to test for the existence of a project. That’s why a 404 is returned here, even if a 403 might be more appropriate.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified project does not exist."
    }

Projects by version 

List projects with version
/api/v3/versions/{id}/projects

This endpoint lists the projects where the given version is available.

The projects returned depend on the sharing settings of the given version, but are also limited to the projects that the current user is allowed to see.

  • Parameters
  • id
    integer (required) Example: 1

    Version id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/versions/2/projects"
        }
      },
      "total": 1,
      "count": 1,
      "_type": "Collection",
      "_embedded": {
        "elements": [
          {
            "_type": "Project",
            "_links": {
              "self": {
                "href": "/api/v3/projects/1",
                "title": "Lorem"
              },
              "categories": {
                "href": "/api/v3/projects/1/categories"
              },
              "versions": {
                "href": "/api/v3/projects/1/versions"
              }
            },
            "id": 1,
            "identifier": "project_identifier",
            "name": "Project example",
            "description": "Lorem ipsum dolor sit amet",
            "createdAt": "2014-05-21T08:51:20Z",
            "updatedAt": "2014-05-21T08:51:20Z"
          }
        ]
      }
    }
  • Response  404
  • Returned if the version does not exist or the client does not have sufficient permissions to see it.

    Required permission: view work packages or manage versions (any project where the given version is available)

    Note: A client without sufficient permissions shall not be able to test for the existence of a version. That’s why a 404 is returned here, even if a 403 might be more appropriate.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified version does not exist."
    }

Work Package Columns 

View Work Package columns
/api/v3/projects/{id}/work_packages/columns

Lists the columns available for work packages of this project in the form of field schemas.

  • Parameters
  • id
    integer (required) Example: 1

    Project id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Schema",
      "_links": {
        "self": {
          "href": "/api/v3/example/schema"
        }
      },
      "lockVersion": {
        "name": "Resource Version",
        "type": "Integer",
        "writable": false
      },
      "subject": {
        "name": "Subject",
        "type": "String",
        "minLength": 1,
        "maxLength": 255
      },
      "status": {
        "_links": {
          "allowedValues": [
            {
              "href": "/api/v3/statuses/1",
              "title": "New"
            },
            {
              "href": "/api/v3/statuses/2",
              "title": "Closed"
            }
          ]
        },
        "name": "Status",
        "type": "Status",
        "_embedded": {
          "allowedValues": [
            {
              "_links": {
                "self": {
                  "href": "/api/v3/statuses/1"
                }
              },
              "_type": "Status",
              "id": 1,
              "name": "New",
              "position": 1,
              "isDefault": true,
              "isClosed": false,
              "defaultDoneRatio": 0,
              "createdAt": "2014-05-21T08:51:20Z",
              "updatedAt": "2014-05-21T09:12:00Z"
            },
            {
              "_links": {
                "self": {
                  "href": "/api/v3/statuses/2"
                }
              },
              "_type": "Status",
              "id": 2,
              "name": "Closed",
              "position": 2,
              "isDefault": false,
              "isClosed": true,
              "defaultDoneRatio": 100,
              "createdAt": "2014-05-21T08:51:20Z",
              "updatedAt": "2014-05-21T09:12:00Z"
            }
          ]
        }
      }
    }
  • Response  403
  • Returned if the client is not allowed to see the available columns of work packages on this project.

    Required permission: view work packages

    Note that you will only receive this error, if you are at least allowed to see the corresponding project.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to see work packages of this project."
    }
  • Response  404
  • Returned if the project does not exist or the client does not have sufficient permissions to see it.

    Required permission: view project

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified project does not exist."
    }

Queries 

LinkDescriptionTypeConstraintsSupported operationsCondition
selfThis queryQuerynot nullREAD
userThe user that owns this queryUsernot nullREAD
projectThe project on which this query operatesProjectREAD

Local Properties

PropertyDescriptionTypeConstraintsSupported operations
idQuery idIntegerx > 0READ
nameQuery nameStringREAD
filtersAn object describing the queries filter conditionsObjectREAD
columnNamesOrdered list of properties to be shown in this queryString[]READ
sortCriteriaAn object describing the sorting rules of this queryObjectREAD
groupByThe property to group results of this query byStringREAD
displaySumsShould sums (of supported properties) be shown?BooleanREAD
isPublicCan users besides the owner see the query?BooleanREAD
isStarredShould the query be highlighted to the user?BooleanREAD

Query 

View query
/api/v3/queries/{id}

might be subject to change in the future

  • Parameters
  • id
    integer (required) Example: 1

    Query id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Query",
      "_links": {
        "self": {
          "href": "/api/v3/queries/2",
          "title": "My work packages"
        },
        "project": {
          "href": "/api/v3/projects/1",
          "title": "A project"
        },
        "user": {
          "href": "/api/v3/users/1",
          "title": "John Sheppard"
        }
      },
      "id": 2,
      "name": "My work packages",
      "filters": [
        {
          "status": {
            "operator": "o",
            "values": null
          }
        },
        {
          "assignee": {
            "operator": "=",
            "values": [
              "me"
            ]
          }
        }
      ],
      "isPublic": false,
      "columnNames": [
        "type",
        "status",
        "priority",
        "subject",
        "assignee"
      ],
      "sortCriteria": [
        [
          "parent",
          "desc"
        ]
      ],
      "groupBy": null,
      "displaySums": false,
      "isStarred": true
    }
  • Response  404
  • Returned if the query does not exist or the client does not have sufficient permissions to see it.

    Required condition: query belongs to user or query is public

    Required permission: view work package in queries project

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified query does not exist."
    }

Star Query 

Star query
/api/v3/queries/{id}/star
  • Parameters
  • id
    integer (required) Example: 1

    Query id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Query",
      "_links": {
        "self": {
          "href": "/api/v3/queries/2",
          "title": "My work packages"
        },
        "project": {
          "href": "/api/v3/projects/1",
          "title": "Lorem ipsum"
        },
        "user": {
          "href": "/api/v3/users/1",
          "title": "John Sheppard - admin"
        }
      },
      "id": 2,
      "name": "My work packages",
      "filters": [
        {
          "status": {
            "operator": "o",
            "values": null
          }
        },
        {
          "assignee": {
            "operator": "=",
            "values": [
              "me"
            ]
          }
        }
      ],
      "isPublic": "false",
      "columnNames": [
        "type",
        "status",
        "priority",
        "subject",
        "assignee"
      ],
      "sortCriteria": [
        [
          "parent",
          "desc"
        ]
      ],
      "groupBy": null,
      "displaySums": "false",
      "isStarred": true
    }
  • Response  400
  • Occurs when the client did not send an empty request body.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
      "message": "The request body was not empty."
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: for own queries none; for public queries: manage public queries

    Note that you will only receive this error, if you are at least allowed to see the corresponding query.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to star this query."
    }
  • Response  404
  • Returned if the query does not exist or the client does not have sufficient permissions to see it.

    Required condition: query belongs to user or query is public

    Required permission: view work package in queries project

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified query does not exist."
    }

Unstar Query 

Unstar query
/api/v3/queries/{id}/unstar
  • Parameters
  • id
    integer (required) Example: 1

    Query id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Query",
      "_links": {
        "self": {
          "href": "/api/v3/queries/2",
          "title": "My work packages"
        },
        "project": {
          "href": "/api/v3/projects/1",
          "title": "Lorem ipsum"
        },
        "user": {
          "href": "/api/v3/users/1",
          "title": "John Sheppard - admin"
        }
      },
      "id": 2,
      "name": "My work packages",
      "filters": [
        {
          "status": {
            "operator": "o",
            "values": null
          }
        },
        {
          "assignee": {
            "operator": "=",
            "values": [
              "me"
            ]
          }
        }
      ],
      "isPublic": "false",
      "columnNames": [
        "type",
        "status",
        "priority",
        "subject",
        "assignee"
      ],
      "sortCriteria": [
        [
          "parent",
          "desc"
        ]
      ],
      "groupBy": null,
      "displaySums": "false",
      "isStarred": "false"
    }
  • Response  400
  • Occurs when the client did not send an empty request body.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
      "message": "The request body was not empty."
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: for own queries none; for public queries: manage public queries

    Note that you will only receive this error, if you are at least allowed to see the corresponding query.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to unstar this query."
    }
  • Response  404
  • Returned if the query does not exist or the client does not have sufficient permissions to see it.

    Required condition: query belongs to user or query is public

    Required permission: view work package in queries project

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified query does not exist."
    }

Relations 

Work packages may be related to each other in different ways.

+--------------+                            +--------------+
|              | 1                        1 |              |
| Work package +-------------+--------------+ Work package |
|              | from        |           to |              |
+--------------+             |              +--------------+
                      +------+-------+
                      |   Relation   |
                      +--------------+
                      | type         |
                      | reverseType  |
                      | description  |
                      | delay        |
                      +--------------+

Actions

LinkDescriptionCondition
updateUpdates the relation between two work packages via a form Permission: manage work package relations
updateImmediatelyUpdates the relation between two work packages Permission: manage work package relations
deleteDestroys the relation between the two work packages Permission: manage work package relations

Linked Properties

LinkDescriptionTypeConstraintsSupported operationsCondition
selfThis relationRelationnot nullREAD Permission: view work packages
schemaThe schema of this relationSchemanot nullREAD
fromThe emanating work packageWorkPackagenot nullREAD Permission: view work packages
toThe work package the relation ends inWorkPackagenot nullREAD Permission: view work packages

Local Properties

PropertyDescriptionTypeConstraintsSupported operations
idRelation IDIntegerx > 0READ
nameThe internationalized name of this kind of relationStringREAD
typeWhich kind of relation (blocks, precedes, etc.)Stringin: relates, duplicates, duplicated, blocks, blocked, precedes, follows, includes, partof, requires, requiredREAD / WRITE
reverseTypeThe kind of relation from the other WP’s perspectiveStringin: relates, duplicates, duplicated, blocks, blocked, precedes, follows, includes, partof, requires, requiredREAD
descriptionShort text further describing the relationStringREAD / WRITE
delay*The delay in days between closing of from and start of toIntegerx >= 0READ / WRITE

* Only applicable for some relation types such as “follows”. You can check using the relation by schema endpoint at /api/v3/relations/schema/{type}.

Relation 

View Relation
/api/v3/relations/{id}
  • Parameters
  • id
    integer (required) Example: 1

    Relation id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/relations/1"
        },
        "update": {
          "href": "/api/v3/relations/1/form",
          "method": "POST"
        },
        "updateImmediately": {
          "href": "/api/v3/relations/1",
          "method": "PATCH"
        },
        "delete": {
          "href": "/api/v3/relations/1",
          "method": "DELETE"
        },
        "from": {
          "href": "/api/v3/work_packages/42",
          "title": "Steel Delivery"
        },
        "to": {
          "href": "/api/v3/work_packages/84",
          "title": "Bending the steel"
        }
      },
      "_type": "Relation",
      "id": 1,
      "name": "precedes",
      "type": "precedes",
      "reverseType": "follows",
      "description": "We can't bend the steel before it's been delivered!",
      "delay": 0
    }
  • Response  404
  • Returned if the relation does not exist or the client does not have sufficient permissions to see it.

    Required permission: view work packages for the involved work packages

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified relation does not exist."
    }
Edit Relation
/api/v3/relations/{id}

When calling this endpoint the client provides a single object, containing the properties and links that it wants to change, in the body. It is only allowed to provide properties or links supporting the write operation.

Note that changing the type of a relation invariably also changes the respective reverseType as well as the “name” of it. The returned Relation object will reflect that change. For instance if you change a Relation’s type to “follows” then the reverseType will be changed to precedes.

  • Parameters
  • id
    integer (required) Example: 1

    Relation ID

  • Request  Update Relation
  • Headers
    Content-Type: application/json
    Body
    {
        "type": "blocks",
        "description": "Actually the supplier has to bend the steel before they can deliver it."
        "delay": 3
    }
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/relations/1"
        },
        "update": {
          "href": "/api/v3/relations/1/form",
          "method": "POST"
        },
        "updateImmediately": {
          "href": "/api/v3/relations/1",
          "method": "PATCH"
        },
        "delete": {
          "href": "/api/v3/relations/1",
          "method": "DELETE"
        },
        "from": {
          "href": "/api/v3/work_packages/42",
          "title": "Steel Delivery"
        },
        "to": {
          "href": "/api/v3/work_packages/84",
          "title": "Bending the steel"
        }
      },
      "_type": "Relation",
      "id": 1,
      "name": "precedes",
      "type": "precedes",
      "reverseType": "follows",
      "description": "We can't bend the steel before it's been delivered!",
      "delay": 0
    }
  • Response  400
  • Occurs when the client did not send a valid JSON object in the request body.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
      "message": "The request body was not a single JSON object."
    }
  • Response  404
  • Returned if the relation does not exist or the client does not have sufficient permissions to see it.

    Required permission: manage work package relations

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified relation does not exist."
    }
  • Response  422
  • Returned if:

    • the client tries to modify a read-only property (PropertyIsReadOnly)

    • a constraint for a property was violated (PropertyConstraintViolation)

    • the client provides a link to an invalid resource (ResourceTypeMismatch) or a work package that does not exist or for which the client does not have sufficient permissions to see it (required permissions: view work packages for the involved work packages).

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
      "message": "Delay must be a number greater than or equal to 0",
      "_embedded": {
        "details": {
          "attribute": "delay"
        }
      }
    }
Delete Relation
/api/v3/relations/{id}

Deletes the relation.

  • Parameters
  • id
    integer (required) Example: 1

    Relation ID

  • Response  204
  • Returned if the relation was deleted successfully. The response body is empty.

    Headers
    Content-Type: application/hal+json
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: manage work package relations

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to delete this relation."
    }
  • Response  404
  • Returned if the relation does not exist or the client does not have sufficient permissions to see it.

    Required permission: manage work package relations

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified relation does not exist."
    }

Relation schema 

View relation schema
/api/v3/relations/schema
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Schema",
      "_links": {
        "self": {
          "href": "/api/v3/relations/schema"
        }
      },
      "id": {
        "name": "ID",
        "type": "Integer",
        "writable": false
      },
      "type": {
        "name": "Type",
        "type": "String",
        "writable": true
      },
      "reverseType": {
        "name": "Reverse Type",
        "type": "String",
        "writable": false
      },
      "description": {
        "name": "Description",
        "type": "String",
        "writable": true
      },
      "from": {
        "name": "From work package",
        "type": "WorkPackage",
        "writable": false
      },
      "to": {
        "name": "To work package",
        "type": "WorkPackage",
        "writable": false
      },
      "delay": {
        "name": "Delay",
        "type": "Integer",
        "writable": true
      }
    }

Relation schema for type 

The exact schema for a relation may depend on it’s type. For instance the “follows” relation has an additional “delay” field which is not applicable for the other relations.

View relation schema for type
/api/v3/relations/schema/{type}
  • Parameters
  • type
    string (required) Example: follows

    Type of the schema

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Schema",
      "_links": {
        "self": {
          "href": "/api/v3/relations/schema"
        }
      },
      "id": {
        "name": "ID",
        "type": "Integer",
        "writable": false
      },
      "type": {
        "name": "Type",
        "type": "String",
        "writable": true
      },
      "reverseType": {
        "name": "Reverse Type",
        "type": "String",
        "writable": false
      },
      "description": {
        "name": "Description",
        "type": "String",
        "writable": true
      },
      "from": {
        "name": "From work package",
        "type": "WorkPackage",
        "writable": false
      },
      "to": {
        "name": "To work package",
        "type": "WorkPackage",
        "writable": false
      },
      "delay": {
        "name": "Delay",
        "type": "Integer",
        "writable": true
      }
    }
  • Response  404
  • Returned if the relation type does not exist or the client does not have sufficient permissions to see it.

    Required permission: manage work package relations

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified relation type does not exist."
    }

Relations 

List Relations
/api/v3/relations{?offset,pageSize,filters,sortBy}

Lists all relations according to the given (optional, logically conjunctive) filters and ordered by ID. The response only includes relations between work packages which the user is allowed to see.

  • Parameters
  • offset
    integer (optional) Default: 0 Example: 5

    Page number inside the requested collection

    pageSize
    integer (optional) Example: 20

    Number of elements to display per page

    filters
    string (optional) Example: [{ "from": { "operator": "=", "values": 42 }" }]

    JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. Valid fields to filter by are: from (ID of work package from which the filtered relations emanates), to (ID of work package to which this related points), involved (ID of either the from or the to work package.), type (The type of relation to filter by, e.g. “follows”)

    sortBy
    string (optional) Example: [["type", "asc"]]

    JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint.

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/relations"
        }
      },
      "total": 3,
      "count": 1,
      "_type": "Collection",
      "_embedded": {
        "elements": [
          {
            "_links": {
              "self": {
                "href": "/api/v3/relations/1"
              },
              "update": {
                "href": "/api/v3/relations/1/form",
                "method": "POST"
              },
              "updateImmediately": {
                "href": "/api/v3/relations/1",
                "method": "PATCH"
              },
              "delete": {
                "href": "/api/v3/relations/1",
                "method": "DELETE"
              },
              "from": {
                "href": "/api/v3/work_packages/42",
                "title": "Steel Delivery"
              },
              "to": {
                "href": "/api/v3/work_packages/84",
                "title": "Bending the steel"
              }
            },
            "_type": "Relation",
            "id": 1,
            "name": "precedes",
            "type": "precedes",
            "reverseType": "follows",
            "description": "We can't bend the steel before it's been delivered!",
            "delay": 0
          }
        ]
      }
    }

Relation edit form 

This endpoint returns a form to allow a guided creation of a new work package relation. The returned form will be pre-filled with default values for every property, if available.

For more details and all possible responses see the general specification of Forms.

Relation edit form
/api/v3/relations/{id}/form
  • Parameters
  • id
    integer (required) Example: 1

    ID of the relation being modified

  • Request
  • Body
    {
      "_type": "Relation",
      "type": "follows",
      "description": "let it rest for 3 days",
      "delay": 3
    }
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/relations/form"
        },
        "validate": {
          "href": "/api/v3/relations/form",
          "method": "POST"
        },
        "commit": {
          "href": "/api/v3/relations",
          "method": "PATCH"
        }
      },
      "_type": "Form",
      "_embedded": {
        "payload": {
          "_links": {
            "from": {
              "href": "/api/v3/work_packages/4534"
            },
            "to": {
              "href": "/api/v3/work_packages/3857"
            }
          },
          "_type": "WorkPackage",
          "type": "follows",
          "delay": 3,
          "description": "let it rest for 3 days"
        },
        "schema": {
          "_type": "Schema",
          "_links": {
            "self": {
              "href": "/api/v3/relations/schema"
            }
          },
          "id": {
            "name": "ID",
            "type": "Integer",
            "writable": false
          },
          "type": {
            "name": "Type",
            "type": "String",
            "writable": true,
            "allowedValues": [
              "relates",
              "duplicates",
              "duplicated",
              "blocks",
              "blocked",
              "precedes",
              "follows",
              "includes",
              "partof",
              "requires",
              "required"
            ]
          },
          "reverseType": {
            "name": "Reverse Type",
            "type": "String",
            "writable": false
          },
          "description": {
            "name": "Description",
            "type": "String",
            "writable": true
          },
          "from": {
            "name": "From work package",
            "type": "WorkPackage",
            "writeable": false
          },
          "to": {
            "name": "To work package",
            "type": "WorkPackage",
            "writable": false
          },
          "delay": {
            "name": "Delay",
            "type": "Integer",
            "writable": true
          }
        },
        "validationErrors": {
          "from": {
            "_type": "Error",
            "errorIdentifier": "urn:openproject-org:api:v3:errors:BadExampleError",
            "message": "For the purpose of this example we need a validation error. The remainder of the response pretends there were no errors."
          }
        }
      }
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: manage work package relations

    Note that you will only receive this error, if you are at least allowed to see the involved work packages.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to edit the specified relation."
    }
  • Response  404
  • Returned if the relation does not exist or the client does not have sufficient permissions to see it.

    Required permission: view (involved) work package(s), manage work package relations

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified relation does not exist."
    }

Previewing 

Throughout OpenProject user input for many properties can be formatted (e.g. using Textile). Using the appropriate rendering endpoint it is possible to render custom formatted inputs into HTML and thus receive a preview of the rendered text.

The request to a rendering endpoint must always have a MIME-Type of text/plain. The request body is the actual string that shall be rendered as HTML string.

Textile 

Preview Textile document
/api/v3/render/textile{?context}
  • Parameters
  • context
    string (optional) Example: /api/v3/work_packages/42

    API-Link to the context in which the rendering occurs, for example a specific work package.

    If left out only context-agnostic rendering takes place. Please note that OpenProject features textile-extensions that can only work given a context (e.g. display attached images).

    Supported contexts:

    • /api/v3/work_packages/{id} - an existing work package
  • Request
  • Headers
    Content-Type: text/plain
    Body
    Hello world! "This":http://example.com *is* textile!
  • Response  200
  • Headers
    Content-Type: text/html
    Body
    <p>Hello world! <a href="http://example.com">This</a> <strong>is</strong> textile!</p>
  • Response  400
  • Returned if the context passed by the client is not valid (e.g. unknown).

    Note that this response will also occur when the requesting user is not allowed to see the context resource (e.g. limited work package visibility).

    Headers
    Content-Type: application/json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRenderContext",
      "message": "Could not render textile string in the given context."
    }
  • Response  415
  • Returned if the Content-Type indicated in the request is not text/plain.

    Headers
    Content-Type: application/json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
      "message": "Expected Content-Type to be 'text/plain' but got 'application/json'."
    }

Plain Text 

Preview plain document
/api/v3/render/plain
  • Request
  • Headers
    Content-Type: text/plain
    Body
    Hello world! This *is* plain text!
  • Response  200
  • Headers
    Content-Type: text/html
    Body
    <p>Hello world! This *is* plain text!</p>
  • Response  415
  • Returned if the Content-Type indicated in the request is not text/plain.

    Headers
    Content-Type: application/json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
      "message": "Expected Content-Type to be 'text/plain' but got 'application/json'."
    }

Revisions 

Revisions are sets of updates to files in the context of repositories linked in OpenProject.

Linked Properties

LinkDescriptionTypeConstraintsSupported operations
selfThis revisionRevisionnot nullREAD
projectThe project to which the revision belongsProjectnot nullREAD
authorThe user that added this revision, if the authorName was mapped to a user in OpenProjectUserREAD
showRevisionA URL to the repository view (outside APIv3) showing this revision-not nullREAD

Local Properties

PropertyDescriptionTypeConstraintsSupported operations
idRevision’s id, assigned by OpenProjectIntegerx > 0READ
identifierThe raw SCM identifier of the revision (e.g. full SHA hash)Stringnot nullREAD
formattedIdentifierThe SCM identifier of the revision, formatted (e.g. shortened unambiguous SHA hash). May be identical to identifier in many casesStringnot nullREAD
authorNameThe name of the author that committed this revision. Note that this name is retrieved from the repository and does not identify a user in OpenProject.Stringnot nullREAD
messageThe commit message of the revisionFormattablenot nullREAD
createdAtThe time this revision was committed to the repositoryDateTimenot nullREAD

Revision 

View revision
/api/v3/revisions/{id}
  • Parameters
  • id
    integer (required) Example: 1

    Revision id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
        "_type": "Revision",
        "_links": {
            "self": {
                "href": "/api/v3/revisions/1"
            },
            "project" {
                "href": "/api/v3/projects/1"
            },
            "author": {
                "href": "/api/v3/users/1"
            },
            "showRevision": {
                "href": "/projects/identifier/repository/revision/11f4b07"
            }
        },
        "id": 1,
        "identifier": "11f4b07dff4f4ce9548a52b7d002daca7cd63ec6",
        "formattedIdentifier": "11f4b07",
        "authorName": "Some Developer",
        "message": {
            "format": "plain",
            "raw": "This revision provides new features\n\nAn elaborate description",
            "html": "<p>This revision provides new features<br/><br/>An elaborate description</p>"
        },
        "createdAt": "2015-07-21T13:36:59Z"
    }
  • Response  404
  • Returned if the revision does not exist or the client does not have sufficient permissions to see it.

    Required permission: view changesets for the project the repository is created in.

    Note: A client without sufficient permissions shall not be able to test for the existence of a revision. That’s why a 404 is returned here, even if a 403 might be more appropriate.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified revision does not exist."
    }

Root 

The root resource contains links to available resources in the API. By following these links a client should be able to discover further resources in the API.

Note: Currently there is no list action for projects available. A client will therefore have to know links to projects and can’t (yet) discover them.

LinkDescriptionTypeNullableSupported operationsCondition
configurationThe configuration of this OpenProject instanceConfigurationREAD
userThe user currently logged-inUserREADlogged in
userPreferencesThe preferences of the logged-in userUserPreferenceREADlogged in
prioritiesList of available prioritiesCollectionREAD Permission View work packages in any project
statusesList of available work package statusesCollectionREAD Permission View work packages in any project
typesList of available work package typesCollectionREAD Permission View work packages in any project
workPackagesList of all work packagesCollectionREAD Permission View work packages in any project
usersList of all usersCollectionREAD Permission Administrator

Local Properties

PropertyDescriptionTypeConditionSupported operations
instanceNameThe name of the OpenProject instanceStringREAD
coreVersionThe OpenProject core version number for the instanceStringREAD

Root 

View root
/api/v3
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
        "_links" : {
            "configuration" : {
                "href" : "/api/v3/configuration"
            },
            "user": {
                "href": "/api/v3/users/1",
                "title": "John Sheppard"
            };
            "userPreferences" : {
                "href" : "/api/v3/my_preferences"
            },
            "priorities" : {
                "href" : "/api/v3/priorities"
            },
            "relations" : {
                "href" : "/api/v3/relations"
            },
            "statuses" : {
                "href" : "/api/v3/statuses"
            },
            "types" : {
                "href" : "/api/v3/types"
            },
            "workPackages" : {
                "href" : "/api/v3/work_packages"
            },
            "users": {
                "href" : "/api/v3/users"
            }
        },
        "instanceName" : "My own OpenProject",
        "coreVersion" : "6.1.0"
    }

Schemas 

Linked Properties

LinkDescriptionTypeNullableSupported operations
selfThis schemaSchemaREAD

The schema provides more detailed information about the properties of a resource. The schema is represented by a dictionary containing names of resource properties as keys and objects describing the corresponding property as values. These objects are called field schema and form the core of the schema representation, each of them can contain its own _links and _embedded section.

Field schema

Linked Properties

PropertyDescription
allowedValuesList of resources that are assignable by the current user.

The allowedValues can either contain a list of canonical links or just a single link to a collection resource. This is an optimization to allow efficient handling of both small resource lists (that can be enumerated inline) and large resource lists (requiring one or more separate requests).

Local Properties

PropertyDescriptionTypeDefault
nameHuman readable name of the property as it could be displayed in a UIString
typeThe data type of the properties valuesMetaType
minLengthThe value of the property must at least contain the specified amount of charactersInteger0
maxLengthThe value of the property must at most contain the specified amount of charactersInteger
regularExpressionThe value of the property must match the given regular expression (if not null)Stringnull
requiredIf true this property is not nullableBooleantrue
writableIf false it is not allowed to change the properties valueBooleantrue

All of the above properties that do not have a default value must be present in the schema. For properties that have a default value, the client can assume the default value, if the property is missing.

Note that regular expressions used in the API follow the rules of Ruby Regular Expressions.

Example Schema 

view the schema
/api/v3/example/schema

This is an example of how a schema might look like. Note that this endpoint does not exist in the actual implementation.

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Schema",
      "_links": {
        "self": {
          "href": "/api/v3/example/schema"
        }
      },
      "lockVersion": {
        "name": "Resource Version",
        "type": "Integer",
        "writable": false
      },
      "subject": {
        "name": "Subject",
        "type": "String",
        "minLength": 1,
        "maxLength": 255
      },
      "status": {
        "_links": {
          "allowedValues": [
            {
              "href": "/api/v3/statuses/1",
              "title": "New"
            },
            {
              "href": "/api/v3/statuses/2",
              "title": "Closed"
            }
          ]
        },
        "name": "Status",
        "type": "Status",
        "_embedded": {
          "allowedValues": [
            {
              "_links": {
                "self": {
                  "href": "/api/v3/statuses/1"
                }
              },
              "_type": "Status",
              "id": 1,
              "name": "New",
              "position": 1,
              "isDefault": true,
              "isClosed": false,
              "defaultDoneRatio": 0,
              "createdAt": "2014-05-21T08:51:20Z",
              "updatedAt": "2014-05-21T09:12:00Z"
            },
            {
              "_links": {
                "self": {
                  "href": "/api/v3/statuses/2"
                }
              },
              "_type": "Status",
              "id": 2,
              "name": "Closed",
              "position": 2,
              "isDefault": false,
              "isClosed": true,
              "defaultDoneRatio": 100,
              "createdAt": "2014-05-21T08:51:20Z",
              "updatedAt": "2014-05-21T09:12:00Z"
            }
          ]
        }
      }
    }

Statuses 

Linked Properties

LinkDescriptionTypeConstraintsSupported operations
selfThis statusStatusnot nullREAD

Local Properties

PropertyDescriptionTypeConstraintsSupported operations
idStatus idIntegerx > 0READ
nameStatus nameStringREAD
positionSort index of the statusIntegerREAD
isDefaultBooleanREAD
isClosedare tickets of this status considered closed?BooleanREAD
defaultDoneRatioThe percentageDone being applied when changing to this statusInteger0 <= x <= 100READ

Statuses 

List all Statuses
/api/v3/statuses
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/statuses"
        }
      },
      "total": 6,
      "count": 6,
      "_type": "Collection",
      "_embedded": {
        "elements": [
          {
            "_links": {
              "self": {
                "href": "/api/v3/statuses/1"
              }
            },
            "_type": "Status",
            "id": 1,
            "name": "New",
            "position": 1,
            "isDefault": true,
            "isClosed": false,
            "defaultDoneRatio": 0
          },
          {
            "_links": {
              "self": {
                "href": "/api/v3/statuses/3"
              }
            },
            "_type": "Status",
            "id": 3,
            "name": "Resolved",
            "position": 3,
            "isDefault": false,
            "isClosed": false,
            "defaultDoneRatio": 75
          },
          {
            "_links": {
              "self": {
                "href": "/api/v3/statuses/4"
              }
            },
            "_type": "Status",
            "id": 4,
            "name": "Feedback",
            "position": 4,
            "isDefault": false,
            "isClosed": false,
            "defaultDoneRatio": 25
          },
          {
            "_links": {
              "self": {
                "href": "/api/v3/statuses/5"
              }
            },
            "_type": "Status",
            "id": 5,
            "name": "Closed",
            "position": 5,
            "isDefault": false,
            "isClosed": true,
            "defaultDoneRatio": 100
          },
          {
            "_links": {
              "self": {
                "href": "/api/v3/statuses/6"
              }
            },
            "_type": "Status",
            "id": 6,
            "name": "Rejected",
            "position": 6,
            "isDefault": false,
            "isClosed": true,
            "defaultDoneRatio": 100
          },
          {
            "_links": {
              "self": {
                "href": "/api/v3/statuses/2"
              }
            },
            "_type": "Status",
            "id": 2,
            "name": "In Progress",
            "position": 3,
            "isDefault": false,
            "isClosed": false,
            "defaultDoneRatio": 50
          }
        ]
      }
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: view work package (on any project)

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to see the statuses."
    }

Status 

View Status
/api/v3/statuses/{id}
  • Parameters
  • id
    integer (required) Example: 1

    status id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/statuses/1"
        }
      },
      "_type": "Status",
      "id": 1,
      "name": "New",
      "position": 1,
      "isDefault": true,
      "isClosed": false,
      "defaultDoneRatio": 0
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: view work package (on any project)

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to see this status."
    }

String Objects 

Linked Properties

LinkDescriptionTypeConstraintsSupported operations
selfThis string objectStringObjectnot nullREAD

Local Properties

PropertyDescriptionTypeConstraintsSupported operations
valueThe value of the stringStringREAD

String objects are a linkable representation of strings. They merely serve the purpose of making links to strings possible, e.g. to be able to provide allowedValues for a string typed property.

String Object 

View String Object
/api/v3/string_objects?value={value}
  • Parameters
  • value
    string (required) Example: Foo

    The string value being resolved

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/string_objects?value=Foo"
        }
      },
      "_type": "StringObject",
      "value": "Foo"
    }

Types 

Linked Properties

LinkDescriptionTypeConstraintsSupported operations
selfThis typeTypenot nullREAD

Local Properties

PropertyDescriptionTypeConstraintsSupported operations
idType idIntegerx > 0READ
nameType nameStringREAD
colorThe color used to represent this typeColorREAD
positionSort index of the typeIntegerREAD
isDefaultBooleanREAD
isMilestoneDo tickets of this type represent a milestone?BooleanREAD
createdAtTime of creationDateTimeREAD
updatedAtTime of the most recent change to the userDateTimeREAD

Types 

List all Types
/api/v3/types
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/types"
        }
      },
      "total": 2,
      "count": 2,
      "_type": "Collection",
      "_embedded": {
        "elements": [
          {
            "_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:20Z",
            "updatedAt": "2014-05-21T08:51:20Z"
          },
          {
            "_links": {
              "self": {
                "href": "/api/v3/types/2"
              }
            },
            "_type": "Type",
            "id": 2,
            "name": "Feature",
            "color": "#888",
            "position": 2,
            "isDefault": false,
            "isMilestone": false,
            "createdAt": "2014-05-21T08:51:20Z",
            "updatedAt": "2014-05-21T08:51:20Z"
          }
        ]
      }
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: view work package or manage types (on any project)

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to see the types."
    }

Types by Project 

List types available in a project
/api/v3/projects/{project_id}/types

This endpoint lists the types that are available in a given project.

  • Parameters
  • project_id
    integer (required) Example: 1

    ID of the project whoose types will be listed

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/projects/11/types"
        }
      },
      "total": 2,
      "count": 2,
      "_type": "Collection",
      "_embedded": {
        "elements": [
          {
            "_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:20Z",
            "updatedAt": "2014-05-21T08:51:20Z"
          },
          {
            "_links": {
              "self": {
                "href": "/api/v3/types/2"
              }
            },
            "_type": "Type",
            "id": 2,
            "name": "Feature",
            "color": "#888",
            "position": 2,
            "isDefault": false,
            "isMilestone": false,
            "createdAt": "2014-05-21T08:51:20Z",
            "updatedAt": "2014-05-21T08:51:20Z"
          }
        ]
      }
    }
  • Response  404
  • Returned if the project does not exist or the client does not have sufficient permissions to see it.

    Required permission: view work packages or manage types (on given project)

    Note: A client without sufficient permissions shall not be able to test for the existence of a project. That’s why a 404 is returned here, even if a 403 might be more appropriate.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified project does not exist."
    }

Type 

View Type
/api/v3/types/{id}
  • Parameters
  • id
    integer (required) Example: 1

    type id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_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:20Z",
      "updatedAt": "2014-05-21T08:51:20Z"
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: view work package or manage types (on any project)

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to see this type."
    }

UserPreferences 

Linked Properties

LinkDescriptionTypeConstraintsSupported operations
selfThis UserPreferencesUserPreferencesnot nullREAD
userThe user that this preference belongs toUsernot nullREAD

Local Properties

PropertyDescriptionTypeConstraintsSupported operations
hideMailHide mail address from other usersBooleanREAD / WRITE
timeZoneCurrent selected time zoneStringREAD / WRITE
themeCurrent selected themeStringREAD / WRITE
commentSortDescendingSort comments in descending orderBooleanREAD / WRITE
warnOnLeavingUnsavedIssue warning when leaving a page with unsaved textBooleanREAD / WRITE
accessibilityModeEnable accessibility modeBooleanREAD / WRITE

UserPreferences 

Show my preferences
/api/v3/my_preferences
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
        "_type" : "UserPreferences",
        "_links" : {
            "self" : {
                "href" : "/api/v3/my_preferences",
            },
            "user": {
                "href": "/api/v3/users/1",
                "title": "John Sheppard"
            }
        },
        "hideMail" : false,
        "timeZone" : "Europe/Berlin",
        "theme" : "OpenProject",
        "commentSortDescending" : true,
        "warnOnLeavingUnsaved" : true,
        "accessibilityMode" : false
    }
  • Response  401
  • Returned if no user is currently authenticated

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:Unauthenticated",
      "message": "You need to be authenticated to access this resource."
    }
Update UserPreferences
/api/v3/my_preferences

When calling this endpoint the client provides a single object, containing the properties that it wants to change, in the body.

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
      "accessibilityMode": true,
      "timeZone": "Europe/Paris"
    }
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
        "_type" : "UserPreferences",
        "_links" : {
            "self" : {
                "href" : "/api/v3/my_preferences",
            },
            "user": {
                "href": "/api/v3/users/1",
                "title": "John Sheppard"
            }
        },
        "hideMail" : false,
        "timeZone" : "Europe/Berlin",
        "theme" : "OpenProject",
        "commentSortDescending" : true,
        "warnOnLeavingUnsaved" : true,
        "accessibilityMode" : false
    }
  • Response  400
  • Occurs when the client did not send a valid JSON object in the request body.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
      "message": "The request body was not a single JSON object."
    }
  • Response  401
  • Returned if no user is currently authenticated

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:Unauthenticated",
      "message": "You need to be authenticated to access this resource."
    }
  • Response  422
  • Returned if the update contains invalid properties. Reasons are:

    • Specifying an invalid type

    • Using an unknown time zone

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
      "message": "Time zone is not set to one of the allowed values."
    }

Users 

Actions

LinkDescriptionCondition
lockRestrict the user from logging in and performing any actionsnot locked; Permission: Administrator
showLink to the OpenProject user page (HTML)
unlockAllow a locked user to login and act againlocked; Permission: Administrator
updateImmediatelyUpdates the user’s attributes. Permission: Administrator
deletePermanently remove a user from the instance Permission: Administrator, self-delete

Linked Properties

LinkDescriptionTypeConstraintsSupported operationsCondition
selfThis userUsernot nullREAD
auth_sourceLink to the user’s auth source (endpoint not yet implemented)AuthSourceREAD / WRITE Permission: Administrator

Local Properties

PropertyDescriptionTypeConstraintsSupported operationsCondition
idUser’s idIntegerx > 0READ
loginUser’s login nameStringunique, 256 max lengthREAD / WRITE Permission: Administrator
firstNameUser’s first nameString30 max lengthREAD / WRITE Permission: Administrator
lastNameUser’s last nameString30 max lengthREAD / WRITE Permission: Administrator
nameUser’s full name, formatting depends on instance settingsStringREAD
emailUser’s E-Mail addressStringunique, 60 max lengthREAD / WRITEE-Mail address not hidden, Permission: Administrator
adminFlag indicating whether or not the user is an adminBooleanin: [true, false]READ / WRITE Permission: Administrator
avatarURL to user’s avatarUrlREAD
statusThe current activation status of the user (see below)Stringin: [“active”, “registered”, “locked”, “invited”]READ
languageUser’s languageStringISO 639-1READ / WRITE Permission: Administrator
passwordUser’s password for the default password authenticationStringWRITE Permission: Administrator
identity_urlUser’s identity_url for OmniAuth authenticationStringREAD / WRITE Permission: Administrator
createdAtTime of creationDateTimeREAD
updatedAtTime of the most recent change to the userDateTimeREAD

The status of a user can be one of:

  • active - the user can log in with the account right aways

  • invited - the user is invited and is pending registration

If the user’s status is set to active during creation a means of authentication has to be provided which is one of the following:

  • password - The password with which the user logs in.

  • auth_source - Link to an LDAP auth source.

  • identity_url - The identity URL of an OmniAuth authentication provider.

If all of these are missing the creation will fail with an “missing password” error.

The language is limited to those activated in the system.

Due to data privacy, the user’s properties are limited to reveal as little about the user as possible. Thus login, firstName, lastName, language, createdAt and updatedAt are hidden for all users except for admins or the user themselves.

Please note that custom fields are not yet supported by the api although the backend supports them.

User 

View user
/api/v3/users/{id}
  • Parameters
  • id
    integer (required) Example: 1

    User id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
        "_type": "User",
        "_links": {
            "self": {
                "href": "/api/v3/users/1",
                "title": "j.sheppard"
            },
            "show": {
                "href": "/users/1",
                "type": 'text/html'
            },
            "lock": {
                "href": "/api/v3/users/1/lock",
                "method": "POST"
            },
            "updateImmediately": {
                "href": "/api/v3/users/1",
                "method": "PATCH"
            },
            "delete": {
                "href": "/api/v3/users/1",
                "method": "DELETE"
            },
        },
        "id": 1,
        "login": "j.sheppard",
        "firstName": "John",
        "lastName": "Sheppard",
        "email": "shep@mail.com",
        "admin": true,
        "avatar": "https://gravatar/avatar",
        "status": "active",
        "language": "en",
        "createdAt": "2014-05-21T08:51:20Z",
        "updatedAt": "2014-05-21T08:51:20Z"
    }
  • Response  404
  • Returned if the user does not exist or if the API user does not have permission to view them.

    Required permission The user needs to be locked in if the installation is configured to pervent anonymous access

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified user does not exist or you do not have permission to view them."
    }
Update user
/api/v3/users/{id}

Updates the user’s writable attributes. When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body.

  • Parameters
  • id
    integer (required) Example: 1

    User id

  • Request  Update User
  • Headers
    Content-Type: application/json
    Body
    {
      "login": "h.wurst",
      "email": "h.wurst@openproject.com",
      "firstName": "Hans",
      "lastName": "Wurst",
      "admin": true,
      "language": "en"
    }
  • Response  200
  • Body
    {
        "_type": "User",
        "_links": {
            "self": {
                "href": "/api/v3/users/1",
                "title": "j.sheppard"
            },
            "show": {
                "href": "/users/1",
                "type": 'text/html'
            },
            "lock": {
                "href": "/api/v3/users/1/lock",
                "method": "POST"
            },
            "updateImmediately": {
                "href": "/api/v3/users/1",
                "method": "PATCH"
            },
            "delete": {
                "href": "/api/v3/users/1",
                "method": "DELETE"
            },
        },
        "id": 1,
        "login": "j.sheppard",
        "firstName": "John",
        "lastName": "Sheppard",
        "email": "shep@mail.com",
        "admin": true,
        "avatar": "https://gravatar/avatar",
        "status": "active",
        "language": "en",
        "createdAt": "2014-05-21T08:51:20Z",
        "updatedAt": "2014-05-21T08:51:20Z"
    }
  • Response  400
  • Occurs when the client did not send a valid JSON object in the request body.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
      "message": "The request body was not a single JSON object."
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: Administrators only

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to update the account of this user."
    }
  • Response  404
  • Returned if the user does not exist or if the API user does not have the necessary permissions to update it.

    Required permission: Administrators only (exception: users may update their own accounts)

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified user does not exist or you do not have permission to view them."
    }
  • Response  422
  • Returned if:

    • the client tries to modify a read-only property (PropertyIsReadOnly)

    • a constraint for a property was violated (PropertyConstraintViolation)

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
      "message": "The email address is already taken.",
      "_embedded": {
        "details": {
          "attribute": "email"
        }
      }
    }
Delete user
/api/v3/users/{id}

Permanently deletes the specified user account.

  • Parameters
  • id
    integer (required) Example: 1

    User id

  • Response  202
  • Returned if the account was deleted successfully.

    Note that the response body is empty as of now. In future versions of the API a body might be returned, indicating the progress of deletion.

  • Response  403
  • Returned if the client does not have sufficient permissions or if deletion of users was disabled in the instance wide settings.

    Required permission: Administrators only (exception: users might be able to delete their own accounts)

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to delete the account of this user."
    }
  • Response  404
  • Returned if the user does not exist.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified user does not exist."
    }

User Account Locking 

Set Lock
/api/v3/users/{id}/lock
  • Parameters
  • id
    integer (required) Example: 1

    User id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
        "_type": "User",
        "_links": {
            "self": {
                "href": "/api/v3/users/1",
                "title": "j.sheppard"
            },
            "show": {
                "href": "/users/1",
                "type": 'text/html'
            },
            "lock": {
                "href": "/api/v3/users/1/lock",
                "method": "POST"
            },
            "updateImmediately": {
                "href": "/api/v3/users/1",
                "method": "PATCH"
            },
            "delete": {
                "href": "/api/v3/users/1",
                "method": "DELETE"
            },
        },
        "id": 1,
        "login": "j.sheppard",
        "firstName": "John",
        "lastName": "Sheppard",
        "email": "shep@mail.com",
        "admin": true,
        "avatar": "https://gravatar/avatar",
        "status": "active",
        "language": "en",
        "createdAt": "2014-05-21T08:51:20Z",
        "updatedAt": "2014-05-21T08:51:20Z"
    }
  • Response  400
  • Returned if the client tries to lock a user account whose current status does not allow this transition.

    Required permission: Administrators only

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidUserStatusTransition",
      "message": "The current user account status does not allow this operation."
    }
  • Response  403
  • Returned if the client does not have sufficient permissions for locking a user.

    Required permission: Administrators only

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to lock the account of this user."
    }
  • Response  404
  • Returned if the user does not exist.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified user does not exist."
    }
Remove Lock
/api/v3/users/{id}/lock
  • Parameters
  • id
    integer (required) Example: 1

    User id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
        "_type": "User",
        "_links": {
            "self": {
                "href": "/api/v3/users/1",
                "title": "j.sheppard"
            },
            "show": {
                "href": "/users/1",
                "type": 'text/html'
            },
            "lock": {
                "href": "/api/v3/users/1/lock",
                "method": "POST"
            },
            "updateImmediately": {
                "href": "/api/v3/users/1",
                "method": "PATCH"
            },
            "delete": {
                "href": "/api/v3/users/1",
                "method": "DELETE"
            },
        },
        "id": 1,
        "login": "j.sheppard",
        "firstName": "John",
        "lastName": "Sheppard",
        "email": "shep@mail.com",
        "admin": true,
        "avatar": "https://gravatar/avatar",
        "status": "active",
        "language": "en",
        "createdAt": "2014-05-21T08:51:20Z",
        "updatedAt": "2014-05-21T08:51:20Z"
    }
  • Response  400
  • Returned if the client tries to unlock a user account whose current status does not allow this transition.

    Required permission: Administrators only

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidUserStatusTransition",
      "message": "The current user account status does not allow this operation."
    }
  • Response  403
  • Returned if the client does not have sufficient permissions for unlocking a user.

    Required permission: Administrators only

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to unlock the account of this user."
    }
  • Response  404
  • Returned if the user does not exist.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified user does not exist."
    }

Users 

List Users
/api/v3/users{?offset,pageSize,filters,sortBy}

Lists users. Only administrators have permission to do this.

  • Parameters
  • offset
    integer (optional) Default: 1 Example: 25

    Page number inside the requested collection.

    pageSize
    integer (optional) Example: 25

    Number of elements to display per page.

    filters
    string (optional) Example: [{ "status": { "operator": "=", "values": ["invited"] } }, { "group": { "operator": "=", "values": ["1"] } }, { "name": { "operator": "=", "values": ["h.wurst@openproject.com"] } }]

    JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. Currently supported filters are:

    • status: Status the user has

    • group: Name of the group in which to-be-listed users are members.

    • name: Filter users in whose first or last names, or email addresses the given string occurs.

    • login: User’s login

    sortBy
    string (optional) Example: [["status", "asc"]]

    JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint.

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
        "_links": {
            "self": { "href": "/api/v3/users" }
        },
        "total": 2,
        "count": 1,
        "_type": "Collection",
        "_embedded": {
            "elements": [
                {
                    "_type": "User",
                    "_links": {
                        "self": {
                            "href": "/api/v3/users/1",
                            "title": "John Sheppard - j.sheppard"
                        },
                        "showUser": {
                            "href": "/users/1",
                            "type": 'text/html'
                        },
                        "lock": {
                            "href": "/api/v3/users/1/lock",
                            "title": "Set lock on j.sheppard"
                            "method": "POST"
                        },
                        "update": {
                            "href": "/api/v3/users/1",
                            "title": "Update j.sheppard"
                            "method": "PATCH"
                        },
                        "delete": {
                            "href": "/api/v3/users/1",
                            "title": "Delete j.sheppard"
                            "method": "DELETE"
                        }
                    },
                    "id": 1,
                    "login": "j.sheppard",
                    "firstName": "John",
                    "lastName": "Sheppard",
                    "email": "shep@mail.com",
                    "admin": true,
                    "avatar": "https://gravatar/avatar",
                    "status": "active",
                    "language": "en",
                    "createdAt": "2014-05-21T08:51:20Z",
                    "updatedAt": "2014-05-21T08:51:20Z"
                }
            ]
        }
    }
  • Response  400
  • Returned if the client sends an unknown sort column.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
      "message": "Unknown sort column."
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: Administrator

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to list users."
    }
Create User
/api/v3/users{?offset,pageSize,filters,sortBy}

Creates a new user. Only administrators have permission to do so. When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body.

Valid values for status:

  1. “active” - In this case a password has to be provided in addition to the other attributes.
  2. “invited” - In this case nothing but the email address is required. The rest is optional. An invitation will be sent to the user.
  • Request  Create User
  • Headers
    Content-Type: application/json
    Body
    {
      "login": "h.wurst",
      "email": "h.wurst@openproject.com",
      "firstName": "Hans",
      "lastName": "Wurst",
      "admin": false,
      "language": "de",
      "status": "active",
      "password": "hunter5"
    }
  • Request  Invite User
  • Headers
    Content-Type: application/json
    Body
    {
      "email": "h.wurst@openproject.com",
      "firstName": "Hanz",
      "status": "invited"
    }
  • Response  201
  • Body
    {
        "_type": "User",
        "_links": {
            "self": {
                "href": "/api/v3/users/1",
                "title": "j.sheppard"
            },
            "show": {
                "href": "/users/1",
                "type": 'text/html'
            },
            "lock": {
                "href": "/api/v3/users/1/lock",
                "method": "POST"
            },
            "updateImmediately": {
                "href": "/api/v3/users/1",
                "method": "PATCH"
            },
            "delete": {
                "href": "/api/v3/users/1",
                "method": "DELETE"
            },
        },
        "id": 1,
        "login": "j.sheppard",
        "firstName": "John",
        "lastName": "Sheppard",
        "email": "shep@mail.com",
        "admin": true,
        "avatar": "https://gravatar/avatar",
        "status": "active",
        "language": "en",
        "createdAt": "2014-05-21T08:51:20Z",
        "updatedAt": "2014-05-21T08:51:20Z"
    }
  • Response  400
  • Occurs when the client did not send a valid JSON object in the request body.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
      "message": "The request body was not a single JSON object."
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: Administrator

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to create new users."
    }
  • Response  422
  • Returned if:

    • a constraint for a property was violated (PropertyConstraintViolation)
    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
      "message": "The email address is already taken.",
      "_embedded": {
        "details": {
          "attribute": "email"
        }
      }
    }

Versions 

Linked Properties

LinkDescriptionTypeConstraintsSupported operations
selfThis versionVersionnot nullREAD
definingProjectThe project to which the version belongsProjectonly present if the project is visible for the current userREAD
availableInProjectsProjects where this version can be usedProjectsnot nullREAD

Local Properties

PropertyDescriptionTypeConstraintsSupported operations
idVersion idIntegerx > 0READ
nameVersion nameStringnot nullREAD
descriptionFormattablenot nullREAD
startDateDateREAD
endDateDateREAD
statusThe current status of the versionStringnot nullREAD
createdAtTime of creationDateTimenot nullREAD
updatedAtTime of the most recent change to the versionDateTimenot nullREAD

Versions by Project 

List versions available in a project
/api/v3/projects/{project_id}/versions

This endpoint lists the versions that are available in a given project. Note that due to sharing this might be more than the versions defined by that project.

  • Parameters
  • project_id
    integer (required) Example: 1

    ID of the project whoose versions will be listed

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/projects/11/versions"
        }
      },
      "total": 3,
      "count": 3,
      "_type": "Collection",
      "_embedded": {
        "elements": [
          {
            "_links": {
              "self": {
                "href": "/api/v3/versions/11"
              },
              "definingProject": {
                "href": "/api/v3/projects/11"
              },
              "availableInProjects": {
                "href": "/api/v3/versions/11/projects"
              }
            },
            "_type": "Version",
            "id": 11,
            "name": "v3.0 Alpha",
            "description": {
              "format": "plain",
              "raw": "This version has a description",
              "html": "This version has a description"
            },
            "startDate": "2014-11-20",
            "endDate": null,
            "status": "Open"
          },
          {
            "_links": {
              "self": {
                "href": "/api/v3/versions/12"
              },
              "definingProject": {
                "href": "/api/v3/projects/11"
              },
              "availableInProjects": {
                "href": "/api/v3/versions/12/projects"
              }
            },
            "_type": "Version",
            "id": 12,
            "name": "v2.0",
            "description": {
              "format": "plain",
              "raw": "",
              "html": ""
            },
            "startDate": null,
            "endDate": null,
            "status": "Closed"
          },
          {
            "_links": {
              "self": {
                "href": "/api/v3/versions/10"
              },
              "definingProject": {
                "href": "/api/v3/projects/11"
              },
              "availableInProjects": {
                "href": "/api/v3/versions/10/projects"
              }
            },
            "_type": "Version",
            "id": 10,
            "name": "v1.0",
            "description": {
              "format": "plain",
              "raw": "",
              "html": ""
            },
            "startDate": null,
            "endDate": null,
            "status": "Open"
          }
        ]
      }
    }
  • Response  404
  • Returned if the project does not exist or the client does not have sufficient permissions to see it.

    Required permission: view work packages or manage versions (on given project)

    Note: A client without sufficient permissions shall not be able to test for the existence of a project. That’s why a 404 is returned here, even if a 403 might be more appropriate.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified project does not exist."
    }

Version 

View Version
/api/v3/versions/{id}
  • Parameters
  • id
    integer (required) Example: 1

    version id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/versions/11"
        },
        "definingProject": {
          "href": "/api/v3/projects/11"
        },
        "availableInProjects": {
          "href": "/api/v3/versions/11/projects"
        }
      },
      "_type": "Version",
      "id": 11,
      "name": "v3.0 Alpha",
      "description": {
        "format": "plain",
        "raw": "This version has a description",
        "html": "This version has a description"
      },
      "startDate": "2014-11-20",
      "endDate": null,
      "status": "Open"
    }
  • Response  404
  • Returned if the version does not exist or the client does not have sufficient permissions to see it.

    Required permission: view work packages or manage versions (any project where the version is available)

    Note: A client without sufficient permissions shall not be able to test for the existence of a version. That’s why a 404 is returned here, even if a 403 might be more appropriate.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified version does not exist."
    }

Work Packages 

Actions

LinkDescriptionCondition
updateForm endpoint that aids in preparing and performing edits on a WP Permission: edit work package
updateImmediatelyDirectly perform edits on a work package Permission: edit work package
watchAdd current user to WP watcherslogged in; not watching
unwatchRemove current user from WP watcherslogged in; watching
addRelationAdds a relation to this work package. Permission: manage wp relations
addWatcherAdd any user to WP watchers Permission: add watcher
previewMarkupPost markup (e.g. textile) here to receive an HTML-rendered response
addCommentPost comment to WP Permission: add work package notes
removeWatcherRemove any user from WP watchers Permission: delete watcher
addAttachmentAttach a file to the WP Permission: edit work package

Linked Properties

LinkDescriptionTypeConstraintsSupported operationsCondition
selfThis work packageWorkPackagenot nullREAD
schemaThe schema of this work packageSchemanot nullREAD
attachmentsThe files attached to this work packageCollectionnot nullREAD
authorThe person that created the work packageUsernot nullREAD
assigneeThe person that is intended to work on the work packageUserREAD / WRITE
availableWatchersAll users that can be added to the work package as watchers.UserREAD Permission add work package watchers
categoryThe category of the work packageCategoryREAD / WRITE
priorityThe priority of the work packagePrioritynot nullREAD / WRITE
projectThe project to which the work package belongsProjectnot nullREAD / WRITE
responsibleThe person that is responsible for the overall outcomeUserREAD / WRITE
relationsRelations this work package is involved inRelationREAD Permission view work packages
revisionsRevisions that are referencing the work packageRevisionREAD Permission view changesets
statusThe current status of the work packageStatusnot nullREAD / WRITE
timeEntriesAll time entries logged on the work package. Please note that this is a link to an HTML resource for now and as such, the link is subject to change.N/AREAD Permission view time entries
typeThe type of the work packageTypenot nullREAD / WRITE
versionThe version associated to the work packageVersionREAD / WRITE
watchersAll users that are currently watching this work packageCollectionREAD Permission view work package watchers

Local Properties

PropertyDescriptionTypeConstraintsSupported operationsCondition
idWork package idIntegerx > 0READ
lockVersionThe version of the item as used for optimistic lockingIntegerREAD
subjectWork package subjectStringnot null; 1 <= length <= 255READ / WRITE
typeName of the work package’s typeStringnot nullREAD
descriptionThe work package descriptionFormattableREAD / WRITE
parentIdParent work package idIntegerMust be an id of an existing and visible (for the current user) work packageREAD / WRITE
startDateScheduled beginning of a work packageDateCannot be set for parent work packages; must be equal or greater than the earliest possible start date; Exists only on work packages of a non milestone typeREAD / WRITE
dueDateScheduled end of a work packageDateCannot be set for parent work packages; must be greater than or equal to the start date; Exists only on work packages of a non milestone typeREAD / WRITE
dateDate on which a milestone is achievedDateExists only on work packages of a milestone type
estimatedTimeTime a work package likely needs to be completedDurationCannot be set for parent work packagesREAD / WRITE
spentTimeDurationREAD Permission view time entries
percentageDoneAmount of total completion for a work packageInteger0 <= x <= 100; Cannot be set for parent work packagesREAD / WRITE
createdAtTime of creationDateTimeREAD
updatedAtTime of the most recent change to the work packageDateTimeREAD

Note that the properties listed here only cover the built-in properties of the OpenProject Core. Using plug-ins and custom fields a work package might contain various additional properties. A client can consult the schema information to which the work package links. The schema will contain information about all properties of the linking work package, including properties added by plug-ins and custom fields.

Custom fields are identified by a key in the form of customFieldN, where N is an integer. Depending on their type, they can occur as properties or as linked properties. A client has to consult the schema to resolve the human readable name of custom fields.

Properties that cannot be set directly on parent work packages are inferred from their children instead:

  • startDate is the earliest start date from its children

  • dueDate is the latest due date from its children

  • estimatedTime is the sum of estimated times from its children

  • percentageDone is the weighted average of the sum of its children percentages done. The weight is given by the average of its children estimatedHours. However, if the percentage done is given by a work package’s status, then only the status matters and no value is inferred.

Start date can also not be earlier than a due date of any predecessor.

Work Package 

View Work Package
/api/v3/work_packages/{id}{?notify}
  • Parameters
  • id
    integer (required) Example: 1

    Work package id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "WorkPackage",
      "_links": {
        "self": {
          "href": "/api/v3/work_packages/1528",
          "title": "Develop API"
        },
        "schema": {
          "href": "/api/v3/work_packages/schemas/1-1-2"
        },
        "update": {
          "href": "/api/v3/work_packages/1528",
          "method": "patch",
          "title": "Update Develop API"
        },
        "delete": {
          "href": "/work_packages/bulk?ids=1528",
          "method": "delete",
          "title": "Delete Develop API"
        },
        "log_time": {
          "href": "/work_packages/1528/time_entries/new",
          "type": "text/html",
          "title": "Log time on Develop API"
        },
        "move": {
          "href": "/work_packages/1528/move/new",
          "type": "text/html",
          "title": "Move Develop API"
        },
        "attachments": {
          "href": "/api/v3/work_packages/1528/attachments"
        },
        "addAttachment": {
          "href": "/api/v3/work_packages/1528/attachments",
          "method": "post"
        },
        "author": {
          "href": "/api/v3/users/1",
          "title": "OpenProject Admin - admin"
        },
        "responsible": {
          "href": "/api/v3/users/23",
          "title": "Laron Leuschke - Alaina5788"
        },
        "relations": {
          "href": "/api/v3/work_packages/1528/relations",
          "title": "Show relations"
        },
        "revisions": {
          "href": "/api/v3/work_packages/1528/revisions"
        },
        "assignee": {
          "href": "/api/v3/users/11",
          "title": "Emmie Okuneva - Adele5450"
        },
        "priority": {
          "href": "/api/v3/priorities/2",
          "title": "Normal"
        },
        "project": {
          "href": "/api/v3/projects/1",
          "title": "A Test Project"
        },
        "status": {
          "href": "/api/v3/statuses/1",
          "title": "New"
        },
        "type": {
          "href": "/api/v3/types/1",
          "title": "New"
        },
        "version": {
          "href": "/api/v3/versions/1",
          "title": "Version 1"
        },
        "availableWatchers": {
          "href": "/api/v3/work_packages/1528/available_watchers"
        },
        "watch": {
          "href": "/api/v3/work_packages/1528/watchers",
          "method": "post",
          "payload": {
            "user": {
              "href": "/api/v3/users/1"
            }
          }
        },
        "addWatcher": {
          "href": "/api/v3/work_packages/1528/watchers",
          "method": "post",
          "payload": {
            "user": {
              "href": "/api/v3/users/{user_id}"
            }
          },
          "templated": true
        },
        "removeWatcher": {
          "href": "/api/v3/work_packages/1528/watchers/{user_id}",
          "method": "delete",
          "templated": true
        },
        "addRelation": {
          "href": "/api/v3/relations",
          "method": "post",
          "title": "Add relation"
        },
        "changeParent": {
          "href": "/api/v3/work_packages/694",
          "method": "patch",
          "title": "Change parent of Bug in OpenProject"
        },
        "addComment": {
          "href": "/api/v3/work_packages/1528/activities",
          "method": "post",
          "title": "Add comment"
        },
        "parent": {
          "href": "/api/v3/work_packages/1298",
          "title": "nisi eligendi officiis eos delectus quis voluptas dolores"
        },
        "category": {
          "href": "/api/v3/categories/1298",
          "title": "eligend isi"
        },
        "children": [
          {
            "href": "/api/v3/work_packages/1529",
            "title": "Write API documentation"
          }
        ],
        "timeEntries": {
          "href": "/work_packages/1528/time_entries",
          "type": "text/html",
          "title": "Time entries"
        },
        "watchers": {
          "href": "/api/v3/work_packages/1528/watchers"
        },
        "customField3": {
          "href": "api/v3/users/14"
        }
      },
      "id": 1528,
      "subject": "Develop API",
      "description": {
        "format": "textile",
        "raw": "Develop super cool OpenProject API.",
        "html": "<p>Develop super cool OpenProject API.</p>"
      },
      "startDate": null,
      "dueDate": null,
      "estimatedTime": "PT2H",
      "percentageDone": 0,
      "parentId": 1298,
      "customField1": "Foo",
      "customField2": 42,
      "createdAt": "2014-08-29T12:40:53Z",
      "updatedAt": "2014-08-29T12:44:41Z"
    }
  • Response  404
  • Returned if the work package does not exist or the client does not have sufficient permissions to see it.

    Required permission: view work package

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified work package does not exist."
    }
Edit Work Package
/api/v3/work_packages/{id}{?notify}

When calling this endpoint the client provides a single object, containing the properties and links that it wants to change, in the body. Note that it is only allowed to provide properties or links supporting the write operation.

Additionally to the fields the client wants to change, it is mandatory to provide the value of lockVersion which was received by the GET request this change originates from.

The value of lockVersion is used to implement optimistic locking.

  • Parameters
  • id
    integer (required) Example: 1

    Work package id

    notify
    boolean (optional) Default: true Example: false

    Indicates whether change notifications (e.g. via E-Mail) should be sent. Note that this controls notifications for all users interested in changes to the work package (e.g. watchers, author and assignee), not just the current user.

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
        "lockVersion": 13,
        "subject": "Lorem"
        "parentId": "42"
    }
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "WorkPackage",
      "_links": {
        "self": {
          "href": "/api/v3/work_packages/1528",
          "title": "Develop API"
        },
        "schema": {
          "href": "/api/v3/work_packages/schemas/1-1-2"
        },
        "update": {
          "href": "/api/v3/work_packages/1528",
          "method": "patch",
          "title": "Update Develop API"
        },
        "delete": {
          "href": "/work_packages/bulk?ids=1528",
          "method": "delete",
          "title": "Delete Develop API"
        },
        "log_time": {
          "href": "/work_packages/1528/time_entries/new",
          "type": "text/html",
          "title": "Log time on Develop API"
        },
        "move": {
          "href": "/work_packages/1528/move/new",
          "type": "text/html",
          "title": "Move Develop API"
        },
        "attachments": {
          "href": "/api/v3/work_packages/1528/attachments"
        },
        "addAttachment": {
          "href": "/api/v3/work_packages/1528/attachments",
          "method": "post"
        },
        "author": {
          "href": "/api/v3/users/1",
          "title": "OpenProject Admin - admin"
        },
        "responsible": {
          "href": "/api/v3/users/23",
          "title": "Laron Leuschke - Alaina5788"
        },
        "relations": {
          "href": "/api/v3/work_packages/1528/relations",
          "title": "Show relations"
        },
        "revisions": {
          "href": "/api/v3/work_packages/1528/revisions"
        },
        "assignee": {
          "href": "/api/v3/users/11",
          "title": "Emmie Okuneva - Adele5450"
        },
        "priority": {
          "href": "/api/v3/priorities/2",
          "title": "Normal"
        },
        "project": {
          "href": "/api/v3/projects/1",
          "title": "A Test Project"
        },
        "status": {
          "href": "/api/v3/statuses/1",
          "title": "New"
        },
        "type": {
          "href": "/api/v3/types/1",
          "title": "New"
        },
        "version": {
          "href": "/api/v3/versions/1",
          "title": "Version 1"
        },
        "availableWatchers": {
          "href": "/api/v3/work_packages/1528/available_watchers"
        },
        "watch": {
          "href": "/api/v3/work_packages/1528/watchers",
          "method": "post",
          "payload": {
            "user": {
              "href": "/api/v3/users/1"
            }
          }
        },
        "addWatcher": {
          "href": "/api/v3/work_packages/1528/watchers",
          "method": "post",
          "payload": {
            "user": {
              "href": "/api/v3/users/{user_id}"
            }
          },
          "templated": true
        },
        "removeWatcher": {
          "href": "/api/v3/work_packages/1528/watchers/{user_id}",
          "method": "delete",
          "templated": true
        },
        "addRelation": {
          "href": "/api/v3/relations",
          "method": "post",
          "title": "Add relation"
        },
        "changeParent": {
          "href": "/api/v3/work_packages/694",
          "method": "patch",
          "title": "Change parent of Bug in OpenProject"
        },
        "addComment": {
          "href": "/api/v3/work_packages/1528/activities",
          "method": "post",
          "title": "Add comment"
        },
        "parent": {
          "href": "/api/v3/work_packages/1298",
          "title": "nisi eligendi officiis eos delectus quis voluptas dolores"
        },
        "category": {
          "href": "/api/v3/categories/1298",
          "title": "eligend isi"
        },
        "children": [
          {
            "href": "/api/v3/work_packages/1529",
            "title": "Write API documentation"
          }
        ],
        "timeEntries": {
          "href": "/work_packages/1528/time_entries",
          "type": "text/html",
          "title": "Time entries"
        },
        "watchers": {
          "href": "/api/v3/work_packages/1528/watchers"
        },
        "customField3": {
          "href": "api/v3/users/14"
        }
      },
      "id": 1528,
      "subject": "Develop API",
      "description": {
        "format": "textile",
        "raw": "Develop super cool OpenProject API.",
        "html": "<p>Develop super cool OpenProject API.</p>"
      },
      "startDate": null,
      "dueDate": null,
      "estimatedTime": "PT2H",
      "percentageDone": 0,
      "parentId": 1298,
      "customField1": "Foo",
      "customField2": 42,
      "createdAt": "2014-08-29T12:40:53Z",
      "updatedAt": "2014-08-29T12:44:41Z"
    }
  • Response  400
  • Occurs when the client did not send a valid JSON object in the request body.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
      "message": "The request body was not a single JSON object."
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: edit work package

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to edit the content of the work package."
    }
  • Response  404
  • Returned if the work package does not exist or the client does not have sufficient permissions to see it.

    Required permission: view work package

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified work package does not exist."
    }
  • Response  409
  • Returned if the resource was changed since the client requested it. This is determined using the lockVersion property.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:UpdateConflict",
      "message": "Your changes could not be saved, because the work package was changed since you've seen it the last time."
    }
  • Response  422
  • Returned if:

    • the client tries to modify a read-only property (PropertyIsReadOnly)

    • a constraint for a property was violated (PropertyConstraintViolation)

    • the client provides a link to an invalid resource (ResourceTypeMismatch)

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
      "message": "The subject might not be blank.",
      "_embedded": {
        "details": {
          "attribute": "Subject"
        }
      }
    }
Delete Work Package
/api/v3/work_packages/{id}{?notify}

Deletes the work package, as well as:

  • all associated time entries

  • its hierarchy of child work packages

  • Parameters
  • id
    integer (required) Example: 1

    Work package id

  • Response  204
  • Returned if the work package was deleted successfully.

    Note that the response body is empty as of now. In future versions of the API a body might be returned along with an appropriate HTTP status.

    Headers
    Content-Type: application/hal+json
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: delete work package

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to delete this work package."
    }
  • Response  404
  • Returned if the work package does not exist or the client does not have sufficient permissions to see it.

    Required permission: view work package

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified work package does not exist."
    }

Work Package Schema 

View Work Package Schema
/api/v3/work_packages/schemas/{identifier}
  • Parameters
  • identifier
    string (required) Example: 12-13

    Identifier of the schema

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Schema",
      "_links": {
        "self": {
          "href": "/api/v3/example/schema"
        }
      },
      "lockVersion": {
        "name": "Resource Version",
        "type": "Integer",
        "writable": false
      },
      "subject": {
        "name": "Subject",
        "type": "String",
        "minLength": 1,
        "maxLength": 255
      },
      "status": {
        "_links": {
          "allowedValues": [
            {
              "href": "/api/v3/statuses/1",
              "title": "New"
            },
            {
              "href": "/api/v3/statuses/2",
              "title": "Closed"
            }
          ]
        },
        "name": "Status",
        "type": "Status",
        "_embedded": {
          "allowedValues": [
            {
              "_links": {
                "self": {
                  "href": "/api/v3/statuses/1"
                }
              },
              "_type": "Status",
              "id": 1,
              "name": "New",
              "position": 1,
              "isDefault": true,
              "isClosed": false,
              "defaultDoneRatio": 0,
              "createdAt": "2014-05-21T08:51:20Z",
              "updatedAt": "2014-05-21T09:12:00Z"
            },
            {
              "_links": {
                "self": {
                  "href": "/api/v3/statuses/2"
                }
              },
              "_type": "Status",
              "id": 2,
              "name": "Closed",
              "position": 2,
              "isDefault": false,
              "isClosed": true,
              "defaultDoneRatio": 100,
              "createdAt": "2014-05-21T08:51:20Z",
              "updatedAt": "2014-05-21T09:12:00Z"
            }
          ]
        }
      }
    }
  • Response  404
  • Returned if the schema does not exist or the client does not have sufficient permissions to see it.

    Required permission: view work packages (on the project where this schema is used)

    Note: A client without sufficient permissions shall not be able to test for the existence of a project. That’s why a 404 is returned here, even if a 403 might be more appropriate.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified schema does not exist."
    }

Work Package Edit Form 

This endpoint returns a form to allow a guided modification of an existing work package.

For more details and all possible responses see the general specification of Forms.

Work Package Edit Form
/api/v3/work_packages/{id}/form
  • Parameters
  • id
    integer (required) Example: 1

    ID of the work package being modified

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/example/form"
        },
        "validate": {
          "href": "/api/v3/example/form",
          "method": "POST"
        },
        "previewMarkup": {
          "href": "/api/v3/render/textile",
          "method": "POST"
        },
        "commit": {
          "href": "/api/v3/example",
          "method": "PATCH"
        }
      },
      "_type": "Form",
      "_embedded": {
        "payload": {
          "_links": {
            "status": {
              "href": "/api/v3/statuses/1"
            }
          },
          "_type": "Example",
          "lockVersion": 5,
          "subject": "An example title"
        },
        "schema": {
          "_type": "Schema",
          "_links": {
            "self": {
              "href": "/api/v3/example/schema"
            }
          },
          "lockVersion": {
            "type": "Integer",
            "writable": false
          },
          "subject": {
            "type": "String",
            "minLength": 1,
            "maxLength": 255
          },
          "status": {
            "_links": {
              "allowedValues": [
                {
                  "href": "/api/v3/statuses/1",
                  "title": "New"
                },
                {
                  "href": "/api/v3/statuses/2",
                  "title": "Closed"
                }
              ]
            },
            "type": "Status",
            "_embedded": {
              "allowedValues": [
                {
                  "_links": {
                    "self": {
                      "href": "/api/v3/statuses/1"
                    }
                  },
                  "_type": "Status",
                  "id": 1,
                  "name": "New",
                  "position": 1,
                  "isDefault": true,
                  "isClosed": false,
                  "defaultDoneRatio": 0,
                  "createdAt": "2014-05-21T08:51:20Z",
                  "updatedAt": "2014-05-21T09:12:00Z"
                },
                {
                  "_links": {
                    "self": {
                      "href": "/api/v3/statuses/2"
                    }
                  },
                  "_type": "Status",
                  "id": 2,
                  "name": "Closed",
                  "position": 2,
                  "isDefault": false,
                  "isClosed": true,
                  "defaultDoneRatio": 100,
                  "createdAt": "2014-05-21T08:51:20Z",
                  "updatedAt": "2014-05-21T09:12:00Z"
                }
              ]
            }
          }
        },
        "validationErrors": {
          "subject": {
            "_type": "Error",
            "errorIdentifier": "urn:openproject-org:api:v3:errors:BadExampleError",
            "message": "For the purpose of this example we need a validation error. The remainder of the response pretends there were no errors."
          }
        }
      }
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: edit work package

    Note that you will only receive this error, if you are at least allowed to see the corresponding work package.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to edit the specified work package."
    }
  • Response  404
  • Returned if the work package does not exist or the client does not have sufficient permissions to see it.

    Required permission: view work package

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified work package does not exist."
    }

Work Packages 

List Work Packages
/api/v3/work_packages{?notify,offset,pageSize,filters,sortBy,groupBy,showSums}
  • Parameters
  • offset
    integer (optional) Default: 1 Example: 25

    Page number inside the requested collection.

    pageSize
    integer (optional) Example: 25

    Number of elements to display per page.

    filters
    string (optional) Example: [{ "status_id": { "operator": "o", "values": null }" }]

    JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint.

    sortBy
    string (optional) Example: [["status", "asc"]]

    JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint.

    groupBy
    string (optional) Example: status

    The column to group by.

    showSums
     (optional) Default: false 
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/work_packages"
        }
      },
      "total": 2,
      "count": 2,
      "_type": "Collection",
      "_embedded": {
        "elements": [
          {
            "_type": "WorkPackage",
            "_links": {
              "self": {
                "href": "/api/v3/work_packages/1"
              }
            },
            "id": 1,
            "subject": "Skipped other properties for brevity"
          },
          {
            "_type": "WorkPackage",
            "_links": {
              "self": {
                "href": "/api/v3/work_packages/2"
              }
            },
            "id": 2,
            "subject": "Skipped other properties for brevity"
          }
        ]
      }
    }
  • Response  400
  • Returned if the client sends a query parameter, that the server knows, but does not understand. E.g. by providing a syntactically incorrect filters parameter.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
      "message": "Operator can't be blank."
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: view work packages (globally or in any project)

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to see work packages."
    }
Create Work Package
/api/v3/work_packages{?notify,offset,pageSize,filters,sortBy,groupBy,showSums}

When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body. The required fields of a WorkPackage can be found in its schema, which is embedded in the respective form. Note that it is only allowed to provide properties or links supporting the write operation.

A project link must be set when creating work packages through this route.

  • Parameters
  • notify
    boolean (optional) Default: true Example: false

    Indicates whether change notifications (e.g. via E-Mail) should be sent. Note that this controls notifications for all users interested in changes to the work package (e.g. watchers, author and assignee), not just the current user.

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "WorkPackage",
      "_links": {
        "self": {
          "href": "/api/v3/work_packages/1528",
          "title": "Develop API"
        },
        "schema": {
          "href": "/api/v3/work_packages/schemas/1-1-2"
        },
        "update": {
          "href": "/api/v3/work_packages/1528",
          "method": "patch",
          "title": "Update Develop API"
        },
        "delete": {
          "href": "/work_packages/bulk?ids=1528",
          "method": "delete",
          "title": "Delete Develop API"
        },
        "log_time": {
          "href": "/work_packages/1528/time_entries/new",
          "type": "text/html",
          "title": "Log time on Develop API"
        },
        "move": {
          "href": "/work_packages/1528/move/new",
          "type": "text/html",
          "title": "Move Develop API"
        },
        "attachments": {
          "href": "/api/v3/work_packages/1528/attachments"
        },
        "addAttachment": {
          "href": "/api/v3/work_packages/1528/attachments",
          "method": "post"
        },
        "author": {
          "href": "/api/v3/users/1",
          "title": "OpenProject Admin - admin"
        },
        "responsible": {
          "href": "/api/v3/users/23",
          "title": "Laron Leuschke - Alaina5788"
        },
        "relations": {
          "href": "/api/v3/work_packages/1528/relations",
          "title": "Show relations"
        },
        "revisions": {
          "href": "/api/v3/work_packages/1528/revisions"
        },
        "assignee": {
          "href": "/api/v3/users/11",
          "title": "Emmie Okuneva - Adele5450"
        },
        "priority": {
          "href": "/api/v3/priorities/2",
          "title": "Normal"
        },
        "project": {
          "href": "/api/v3/projects/1",
          "title": "A Test Project"
        },
        "status": {
          "href": "/api/v3/statuses/1",
          "title": "New"
        },
        "type": {
          "href": "/api/v3/types/1",
          "title": "New"
        },
        "version": {
          "href": "/api/v3/versions/1",
          "title": "Version 1"
        },
        "availableWatchers": {
          "href": "/api/v3/work_packages/1528/available_watchers"
        },
        "watch": {
          "href": "/api/v3/work_packages/1528/watchers",
          "method": "post",
          "payload": {
            "user": {
              "href": "/api/v3/users/1"
            }
          }
        },
        "addWatcher": {
          "href": "/api/v3/work_packages/1528/watchers",
          "method": "post",
          "payload": {
            "user": {
              "href": "/api/v3/users/{user_id}"
            }
          },
          "templated": true
        },
        "removeWatcher": {
          "href": "/api/v3/work_packages/1528/watchers/{user_id}",
          "method": "delete",
          "templated": true
        },
        "addRelation": {
          "href": "/api/v3/relations",
          "method": "post",
          "title": "Add relation"
        },
        "changeParent": {
          "href": "/api/v3/work_packages/694",
          "method": "patch",
          "title": "Change parent of Bug in OpenProject"
        },
        "addComment": {
          "href": "/api/v3/work_packages/1528/activities",
          "method": "post",
          "title": "Add comment"
        },
        "parent": {
          "href": "/api/v3/work_packages/1298",
          "title": "nisi eligendi officiis eos delectus quis voluptas dolores"
        },
        "category": {
          "href": "/api/v3/categories/1298",
          "title": "eligend isi"
        },
        "children": [
          {
            "href": "/api/v3/work_packages/1529",
            "title": "Write API documentation"
          }
        ],
        "timeEntries": {
          "href": "/work_packages/1528/time_entries",
          "type": "text/html",
          "title": "Time entries"
        },
        "watchers": {
          "href": "/api/v3/work_packages/1528/watchers"
        },
        "customField3": {
          "href": "api/v3/users/14"
        }
      },
      "id": 1528,
      "subject": "Develop API",
      "description": {
        "format": "textile",
        "raw": "Develop super cool OpenProject API.",
        "html": "<p>Develop super cool OpenProject API.</p>"
      },
      "startDate": null,
      "dueDate": null,
      "estimatedTime": "PT2H",
      "percentageDone": 0,
      "parentId": 1298,
      "customField1": "Foo",
      "customField2": 42,
      "createdAt": "2014-08-29T12:40:53Z",
      "updatedAt": "2014-08-29T12:44:41Z"
    }
  • Response  400
  • Occurs when the client did not send a valid JSON object in the request body.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
      "message": "The request body was not a single JSON object."
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: add work packages

    Note that you will only receive this error, if you are at least allowed to see the corresponding project.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to add work packages to this project."
    }
  • Response  404
  • Returned if the project does not exist or the client does not have sufficient permissions to see it.

    Required permissions: view project

    Note: A client without sufficient permissions shall not be able to test for the existence of a project. That’s why a 404 is returned here, even if a 403 might be more appropriate.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified project does not exist."
    }
  • Response  422
  • Returned if:

    • the client tries to write a read-only property

    • a constraint for a property was violated

    • a property was provided in an unreadable format

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
      "message": "The subject might not be blank.",
      "_embedded": {
        "details": {
          "attribute": "Subject"
        }
      }
    }

Work Package Create Form 

This endpoint returns a form to allow a guided creation of a new work package. The returned form will be pre-filled with default values for every property, if available.

For more details and all possible responses see the general specification of Forms. A project link must be set when creating work packages through this route.

Work Package Create Form
/api/v3/work_packages/form
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/example/form"
        },
        "validate": {
          "href": "/api/v3/example/form",
          "method": "POST"
        },
        "previewMarkup": {
          "href": "/api/v3/render/textile",
          "method": "POST"
        },
        "commit": {
          "href": "/api/v3/example",
          "method": "PATCH"
        }
      },
      "_type": "Form",
      "_embedded": {
        "payload": {
          "_links": {
            "status": {
              "href": "/api/v3/statuses/1"
            }
          },
          "_type": "Example",
          "lockVersion": 5,
          "subject": "An example title"
        },
        "schema": {
          "_type": "Schema",
          "_links": {
            "self": {
              "href": "/api/v3/example/schema"
            }
          },
          "lockVersion": {
            "type": "Integer",
            "writable": false
          },
          "subject": {
            "type": "String",
            "minLength": 1,
            "maxLength": 255
          },
          "status": {
            "_links": {
              "allowedValues": [
                {
                  "href": "/api/v3/statuses/1",
                  "title": "New"
                },
                {
                  "href": "/api/v3/statuses/2",
                  "title": "Closed"
                }
              ]
            },
            "type": "Status",
            "_embedded": {
              "allowedValues": [
                {
                  "_links": {
                    "self": {
                      "href": "/api/v3/statuses/1"
                    }
                  },
                  "_type": "Status",
                  "id": 1,
                  "name": "New",
                  "position": 1,
                  "isDefault": true,
                  "isClosed": false,
                  "defaultDoneRatio": 0,
                  "createdAt": "2014-05-21T08:51:20Z",
                  "updatedAt": "2014-05-21T09:12:00Z"
                },
                {
                  "_links": {
                    "self": {
                      "href": "/api/v3/statuses/2"
                    }
                  },
                  "_type": "Status",
                  "id": 2,
                  "name": "Closed",
                  "position": 2,
                  "isDefault": false,
                  "isClosed": true,
                  "defaultDoneRatio": 100,
                  "createdAt": "2014-05-21T08:51:20Z",
                  "updatedAt": "2014-05-21T09:12:00Z"
                }
              ]
            }
          }
        },
        "validationErrors": {
          "subject": {
            "_type": "Error",
            "errorIdentifier": "urn:openproject-org:api:v3:errors:BadExampleError",
            "message": "For the purpose of this example we need a validation error. The remainder of the response pretends there were no errors."
          }
        }
      }
    }

Work Packages by Project 

List Work Packages
/api/v3/projects/{id}/work_packages{?offset,pageSize,filters,sortBy,groupBy,showSums,notify}
  • Parameters
  • id
    integer (required) Example: 1

    Project id

    offset
    integer (optional) Default: 1 Example: 25

    Page number inside the requested collection.

    pageSize
    integer (optional) Example: 25

    Number of elements to display per page.

    filters
    string (optional) Example: [{ "status_id": { "operator": "o", "values": null }" }]

    JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint.

    sortBy
    string (optional) Example: [["status", "asc"]]

    JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint.

    groupBy
    string (optional) Example: status

    The column to group by.

    showSums
     (optional) Default: false 
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/projects/14/work_packages"
        }
      },
      "total": 2,
      "count": 2,
      "_type": "Collection",
      "_embedded": {
        "elements": [
          {
            "_type": "WorkPackage",
            "_links": {
              "self": {
                "href": "/api/v3/work_packages/1"
              }
            },
            "id": 1,
            "subject": "Skipped other properties for brevity"
          },
          {
            "_type": "WorkPackage",
            "_links": {
              "self": {
                "href": "/api/v3/work_packages/2"
              }
            },
            "id": 2,
            "subject": "Skipped other properties for brevity"
          }
        ]
      }
    }
  • Response  400
  • Returned if the client sends a query parameter, that the server knows, but does not understand. E.g. by providing a syntactically incorrect filters parameter.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
      "message": "Operator can't be blank."
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: view work packages

    Note that you will only receive this error, if you are at least allowed to see the corresponding project.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to see the work packages of this project."
    }
  • Response  404
  • Returned if the project does not exist or the client does not have sufficient permissions to see it.

    Required permission: view project

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified project does not exist."
    }
Create Work Package
/api/v3/projects/{id}/work_packages{?offset,pageSize,filters,sortBy,groupBy,showSums,notify}

When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body. The required fields of a WorkPackage can be found in its schema, which is embedded in the respective form. Note that it is only allowed to provide properties or links supporting the write operation.

  • Parameters
  • id
    integer (required) Example: 1

    Project id

    notify
    boolean (optional) Default: true Example: false

    Indicates whether change notifications (e.g. via E-Mail) should be sent. Note that this controls notifications for all users interested in changes to the work package (e.g. watchers, author and assignee), not just the current user.

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "WorkPackage",
      "_links": {
        "self": {
          "href": "/api/v3/work_packages/1528",
          "title": "Develop API"
        },
        "schema": {
          "href": "/api/v3/work_packages/schemas/1-1-2"
        },
        "update": {
          "href": "/api/v3/work_packages/1528",
          "method": "patch",
          "title": "Update Develop API"
        },
        "delete": {
          "href": "/work_packages/bulk?ids=1528",
          "method": "delete",
          "title": "Delete Develop API"
        },
        "log_time": {
          "href": "/work_packages/1528/time_entries/new",
          "type": "text/html",
          "title": "Log time on Develop API"
        },
        "move": {
          "href": "/work_packages/1528/move/new",
          "type": "text/html",
          "title": "Move Develop API"
        },
        "attachments": {
          "href": "/api/v3/work_packages/1528/attachments"
        },
        "addAttachment": {
          "href": "/api/v3/work_packages/1528/attachments",
          "method": "post"
        },
        "author": {
          "href": "/api/v3/users/1",
          "title": "OpenProject Admin - admin"
        },
        "responsible": {
          "href": "/api/v3/users/23",
          "title": "Laron Leuschke - Alaina5788"
        },
        "relations": {
          "href": "/api/v3/work_packages/1528/relations",
          "title": "Show relations"
        },
        "revisions": {
          "href": "/api/v3/work_packages/1528/revisions"
        },
        "assignee": {
          "href": "/api/v3/users/11",
          "title": "Emmie Okuneva - Adele5450"
        },
        "priority": {
          "href": "/api/v3/priorities/2",
          "title": "Normal"
        },
        "project": {
          "href": "/api/v3/projects/1",
          "title": "A Test Project"
        },
        "status": {
          "href": "/api/v3/statuses/1",
          "title": "New"
        },
        "type": {
          "href": "/api/v3/types/1",
          "title": "New"
        },
        "version": {
          "href": "/api/v3/versions/1",
          "title": "Version 1"
        },
        "availableWatchers": {
          "href": "/api/v3/work_packages/1528/available_watchers"
        },
        "watch": {
          "href": "/api/v3/work_packages/1528/watchers",
          "method": "post",
          "payload": {
            "user": {
              "href": "/api/v3/users/1"
            }
          }
        },
        "addWatcher": {
          "href": "/api/v3/work_packages/1528/watchers",
          "method": "post",
          "payload": {
            "user": {
              "href": "/api/v3/users/{user_id}"
            }
          },
          "templated": true
        },
        "removeWatcher": {
          "href": "/api/v3/work_packages/1528/watchers/{user_id}",
          "method": "delete",
          "templated": true
        },
        "addRelation": {
          "href": "/api/v3/relations",
          "method": "post",
          "title": "Add relation"
        },
        "changeParent": {
          "href": "/api/v3/work_packages/694",
          "method": "patch",
          "title": "Change parent of Bug in OpenProject"
        },
        "addComment": {
          "href": "/api/v3/work_packages/1528/activities",
          "method": "post",
          "title": "Add comment"
        },
        "parent": {
          "href": "/api/v3/work_packages/1298",
          "title": "nisi eligendi officiis eos delectus quis voluptas dolores"
        },
        "category": {
          "href": "/api/v3/categories/1298",
          "title": "eligend isi"
        },
        "children": [
          {
            "href": "/api/v3/work_packages/1529",
            "title": "Write API documentation"
          }
        ],
        "timeEntries": {
          "href": "/work_packages/1528/time_entries",
          "type": "text/html",
          "title": "Time entries"
        },
        "watchers": {
          "href": "/api/v3/work_packages/1528/watchers"
        },
        "customField3": {
          "href": "api/v3/users/14"
        }
      },
      "id": 1528,
      "subject": "Develop API",
      "description": {
        "format": "textile",
        "raw": "Develop super cool OpenProject API.",
        "html": "<p>Develop super cool OpenProject API.</p>"
      },
      "startDate": null,
      "dueDate": null,
      "estimatedTime": "PT2H",
      "percentageDone": 0,
      "parentId": 1298,
      "customField1": "Foo",
      "customField2": 42,
      "createdAt": "2014-08-29T12:40:53Z",
      "updatedAt": "2014-08-29T12:44:41Z"
    }
  • Response  400
  • Occurs when the client did not send a valid JSON object in the request body.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
      "message": "The request body was not a single JSON object."
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: add work packages

    Note that you will only receive this error, if you are at least allowed to see the corresponding project.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to add work packages to this project."
    }
  • Response  404
  • Returned if the project does not exist or the client does not have sufficient permissions to see it.

    Required permissions: view project

    Note: A client without sufficient permissions shall not be able to test for the existence of a project. That’s why a 404 is returned here, even if a 403 might be more appropriate.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified project does not exist."
    }
  • Response  422
  • Returned if:

    • the client tries to write a read-only property

    • a constraint for a property was violated

    • a property was provided in an unreadable format

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
      "message": "The subject might not be blank.",
      "_embedded": {
        "details": {
          "attribute": "Subject"
        }
      }
    }

Work Package Create Form 

This endpoint returns a form to allow a guided creation of a new work package. The returned form will be pre-filled with default values for every property, if available.

For more details and all possible responses see the general specification of Forms.

Work Package Create Form
/api/v3/projects/{id}/work_packages/form
  • Parameters
  • id
    integer (required) Example: 1

    ID of the project in which the work package will be created

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/example/form"
        },
        "validate": {
          "href": "/api/v3/example/form",
          "method": "POST"
        },
        "previewMarkup": {
          "href": "/api/v3/render/textile",
          "method": "POST"
        },
        "commit": {
          "href": "/api/v3/example",
          "method": "PATCH"
        }
      },
      "_type": "Form",
      "_embedded": {
        "payload": {
          "_links": {
            "status": {
              "href": "/api/v3/statuses/1"
            }
          },
          "_type": "Example",
          "lockVersion": 5,
          "subject": "An example title"
        },
        "schema": {
          "_type": "Schema",
          "_links": {
            "self": {
              "href": "/api/v3/example/schema"
            }
          },
          "lockVersion": {
            "type": "Integer",
            "writable": false
          },
          "subject": {
            "type": "String",
            "minLength": 1,
            "maxLength": 255
          },
          "status": {
            "_links": {
              "allowedValues": [
                {
                  "href": "/api/v3/statuses/1",
                  "title": "New"
                },
                {
                  "href": "/api/v3/statuses/2",
                  "title": "Closed"
                }
              ]
            },
            "type": "Status",
            "_embedded": {
              "allowedValues": [
                {
                  "_links": {
                    "self": {
                      "href": "/api/v3/statuses/1"
                    }
                  },
                  "_type": "Status",
                  "id": 1,
                  "name": "New",
                  "position": 1,
                  "isDefault": true,
                  "isClosed": false,
                  "defaultDoneRatio": 0,
                  "createdAt": "2014-05-21T08:51:20Z",
                  "updatedAt": "2014-05-21T09:12:00Z"
                },
                {
                  "_links": {
                    "self": {
                      "href": "/api/v3/statuses/2"
                    }
                  },
                  "_type": "Status",
                  "id": 2,
                  "name": "Closed",
                  "position": 2,
                  "isDefault": false,
                  "isClosed": true,
                  "defaultDoneRatio": 100,
                  "createdAt": "2014-05-21T08:51:20Z",
                  "updatedAt": "2014-05-21T09:12:00Z"
                }
              ]
            }
          }
        },
        "validationErrors": {
          "subject": {
            "_type": "Error",
            "errorIdentifier": "urn:openproject-org:api:v3:errors:BadExampleError",
            "message": "For the purpose of this example we need a validation error. The remainder of the response pretends there were no errors."
          }
        }
      }
    }

Relations 

Create Relation
/api/v3/work_packages/{work_package_id}/relations

When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body. The required fields of a Relation can be found in its schema, which is embedded in the respective form. Note that it is only allowed to provide properties or links supporting the write operation.

  • Parameters
  • work_package_id
    integer (required) Example: 1

    Work package id

  • Request  Create Relation
  • Headers
    Content-Type: application/json
    Body
    {
        "_links":
        {
            "from": { "href": "/api/v3/work_packages/42" },
            "to": { "href": "/api/v3/work_packages/84" }
        }
        "type": "duplicates",
        "description": "This is the same thing. Let's track it in one place only, shall we?"
    }
  • Response  201
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/relations/1"
        },
        "update": {
          "href": "/api/v3/relations/1/form",
          "method": "POST"
        },
        "updateImmediately": {
          "href": "/api/v3/relations/1",
          "method": "PATCH"
        },
        "delete": {
          "href": "/api/v3/relations/1",
          "method": "DELETE"
        },
        "from": {
          "href": "/api/v3/work_packages/42",
          "title": "Steel Delivery"
        },
        "to": {
          "href": "/api/v3/work_packages/84",
          "title": "Bending the steel"
        }
      },
      "_type": "Relation",
      "id": 1,
      "name": "precedes",
      "type": "precedes",
      "reverseType": "follows",
      "description": "We can't bend the steel before it's been delivered!",
      "delay": 0
    }
  • Response  400
  • Occurs when the client did not send a valid JSON object in the request body.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
      "message": "The request body was not a single JSON object."
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: manage work package relations

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to create a relation."
    }
  • Response  409
  • Returned if there already exists a relation between the given work packages of any type or if the relation is not allowed.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:UpdateConflict",
      "message": "A relation of that type between the work packages either already exists or is not allowed."
    }
  • Response  422
  • Returned if:

    • the client tries to write a read-only property (PropertyIsReadOnly)

    • a constraint for a property was violated (PropertyConstraintViolation)

    • the client provides a link to an invalid resource (ResourceTypeMismatch)

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
      "message": "Delay must be a number greater than or equal to 0",
      "_embedded": {
        "details": {
          "attribute": "delay"
        }
      }
    }
List relations
/api/v3/work_packages/{work_package_id}/relations

Lists all relations this work package is involved in.

  • Parameters
  • work_package_id
    integer (required) Example: 1

    Work package id

  • Response  302
  • Headers
    Content-Type: text/plain
    Location: /api/v3/relations?involved={work_package_id}
    Body
    You are being redirected to /api/v3/relations?involved={work_package_id}

Work Package Relation Form 

Relation create form
/api/v3/work_packages/{id}/relations/form
  • Parameters
  • id
    integer (required) Example: 1

    ID of the relation being modified

  • Request
  • Body
    {
      "_type": "Relation",
      "type": "follows",
      "from": {
        "href": "/api/v3/work_packages/3493"
      },
      "to": {
        "href": "/api/v3/work_packages/4582"
      },
      "description": "let it rest for 3 days",
      "delay": 3
    }
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/relations/form"
        },
        "validate": {
          "href": "/api/v3/relations/form",
          "method": "POST"
        },
        "commit": {
          "href": "/api/v3/relations",
          "method": "PATCH"
        }
      },
      "_type": "Form",
      "_embedded": {
        "payload": {
          "_links": {
            "from": {
              "href": "/api/v3/work_packages/4534"
            },
            "to": {
              "href": "/api/v3/work_packages/3857"
            }
          },
          "_type": "WorkPackage",
          "type": "follows",
          "delay": 3,
          "description": "let it rest for 3 days"
        },
        "schema": {
          "_type": "Schema",
          "id": {
            "name": "ID",
            "type": "Integer",
            "writable": false
          },
          "type": {
            "name": "Type",
            "type": "String",
            "writable": true,
            "allowedValues": [
              "relates",
              "duplicates",
              "duplicated",
              "blocks",
              "blocked",
              "precedes",
              "follows",
              "includes",
              "partof",
              "requires",
              "required"
            ]
          },
          "reverseType": {
            "name": "Reverse Type",
            "type": "String",
            "writable": false
          },
          "description": {
            "name": "Description",
            "type": "String",
            "writable": true
          },
          "from": {
            "_links": {
              "allowedValues": [
                {
                  "href": "/api/v3/work_packages/{id}"
                }
              ]
            },
            "name": "From work package",
            "type": "WorkPackage",
            "writable": true
          },
          "to": {
            "_links": {
              "allowedValues": {
                "href": "/api/v3/work_packages/{id}/available_relation_candidates",
                "title": "Available work packages to relate to"
              }
            },
            "name": "To work package",
            "type": "WorkPackage",
            "writable": true
          },
          "delay": {
            "name": "Delay",
            "type": "Integer",
            "writable": true
          }
        },
        "validationErrors": {
          "from": {
            "_type": "Error",
            "errorIdentifier": "urn:openproject-org:api:v3:errors:BadExampleError",
            "message": "For the purpose of this example we need a validation error. The remainder of the response pretends there were no errors."
          }
        }
      }
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: manage work package relations

    Note that you will only receive this error, if you are at least allowed to see the involved work packages.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to edit the specified relation."
    }
  • Response  404
  • Returned if the relation does not exist or the client does not have sufficient permissions to see it.

    Required permission: view (involved) work package(s), manage work package relations

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified relation does not exist."
    }

Watchers 

List watchers
/api/v3/work_packages/{work_package_id}/watchers
  • Parameters
  • work_package_id
    integer (required) Example: 1

    Work package id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
        "_links": {
            "self": { "href": "/api/v3/work_packages/14/watchers" }
        },
        "total": 2,
        "count": 2,
        "_type": "Collection",
        "_embedded": {
          "elements": [
            {
                "_type": "User",
                "_links": {
                    "self": {
                        "href": "/api/v3/users/1",
                        "title": "John Sheppard - j.sheppard"
                    },
                    "showUser": {
                        "href": "/users/1",
                        "type": 'text/html'
                    },
                    "lock": {
                        "href": "/api/v3/users/1/lock",
                        "title": "Set lock on j.sheppard"
                        "method": "POST"
                    },
                    "delete": {
                        "href": "/api/v3/users/1",
                        "title": "Delete j.sheppard"
                        "method": "DELETE"
                    }
                },
                "id": 1,
                "login": "j.sheppard",
                "firstName": "John",
                "lastName": "Sheppard",
                "mail": "shep@mail.com",
                "avatar": "https://gravatar/avatar",
                "status": "active",
                "createdAt": "2014-05-21T08:51:20Z",
                "updatedAt": "2014-05-21T08:51:20Z"
            },
            {
                "_type": "User",
                "_links": {
                    "self": {
                        "href": "/api/v3/users/2",
                        "title": "Jim Sheppard - j.sheppard2"
                    },
                    "lock": {
                        "href": "/api/v3/users/2/lock",
                        "title": "Set lock on j.sheppard2"
                        "method": "POST"
                    },
                    "delete": {
                        "href": "/api/v3/users/2",
                        "title": "Delete j.sheppard2"
                        "method": "DELETE"
                    }
                },
                "id": 2,
                "login": "j.sheppard2",
                "firstName": "Jim",
                "lastName": "Sheppard",
                "mail": "shep@mail.net",
                "avatar": "https://gravatar/avatar",
                "status": "active",
                "createdAt": "2014-05-21T08:51:20Z",
                "updatedAt": "2014-05-21T08:51:20Z"
            }]
        }
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: view work package watchers

    Note that you will only receive this error, if you are at least allowed to see the corresponding work package.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to see the watchers of this work package."
    }
  • Response  404
  • Returned if the work package does not exist or the client does not have sufficient permissions to see it.

    Required permission: view work package

    Note that you will effectively not be able to see the watchers of a work package without being able to see the work package.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified work package does not exist."
    }
Add watcher
/api/v3/work_packages/{work_package_id}/watchers

Adds a watcher to the specified work package.

The request is expected to contain a single JSON object, that contains a link object under the user key.

The response will be user added as watcher. In case the user was already watching the work package an HTTP 200 is returned, an HTTP 201 if the user was added as a new watcher.

  • Parameters
  • work_package_id
    integer (required) Example: 1

    Work package id

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
      "user": {
        "href": "/api/v3/users/1"
      }
    }
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
        "_type": "User",
        "_links": {
            "self": {
                "href": "/api/v3/users/1",
                "title": "j.sheppard"
            },
            "show": {
                "href": "/users/1",
                "type": 'text/html'
            },
            "lock": {
                "href": "/api/v3/users/1/lock",
                "method": "POST"
            },
            "updateImmediately": {
                "href": "/api/v3/users/1",
                "method": "PATCH"
            },
            "delete": {
                "href": "/api/v3/users/1",
                "method": "DELETE"
            },
        },
        "id": 1,
        "login": "j.sheppard",
        "firstName": "John",
        "lastName": "Sheppard",
        "email": "shep@mail.com",
        "admin": true,
        "avatar": "https://gravatar/avatar",
        "status": "active",
        "language": "en",
        "createdAt": "2014-05-21T08:51:20Z",
        "updatedAt": "2014-05-21T08:51:20Z"
    }
  • Response  201
  • Headers
    Content-Type: application/hal+json
    Body
    {
        "_type": "User",
        "_links": {
            "self": {
                "href": "/api/v3/users/1",
                "title": "j.sheppard"
            },
            "show": {
                "href": "/users/1",
                "type": 'text/html'
            },
            "lock": {
                "href": "/api/v3/users/1/lock",
                "method": "POST"
            },
            "updateImmediately": {
                "href": "/api/v3/users/1",
                "method": "PATCH"
            },
            "delete": {
                "href": "/api/v3/users/1",
                "method": "DELETE"
            },
        },
        "id": 1,
        "login": "j.sheppard",
        "firstName": "John",
        "lastName": "Sheppard",
        "email": "shep@mail.com",
        "admin": true,
        "avatar": "https://gravatar/avatar",
        "status": "active",
        "language": "en",
        "createdAt": "2014-05-21T08:51:20Z",
        "updatedAt": "2014-05-21T08:51:20Z"
    }
  • Response  400
  • Occurs when the client did not send a valid JSON object in the request body.

    For example:

    • The request did not contain a single JSON object

    • The JSON object did not contain the key user

    • The value of users was not a link object

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
      "message": "The request body was not a single JSON object."
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permissions:

    • view work package (for self)

    • add work package watchers (for other users)

    Note that you will only receive this error, if you are at least allowed to see the corresponding work package.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to add watchers to this work package."
    }
  • Response  404
  • Returned if the work package does not exist or the client does not have sufficient permissions to see it.

    Required permission: view work package

    Note that you will effectively not be able to change the watchers of a work package without being able to see the work package.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified work package does not exist."
    }
  • Response  422
  • Returned if:

    • the client tries to specify a link to a resource that is not a user (ResourceTypeMismatch)

    • the user specified is not allowed to watch that work package (PropertyConstraintViolation)

    • the user specified does not exist (PropertyConstraintViolation)

    Headers
    Content-Type: application/hal+json
    Body
    {
        "_type": "Error",
        "errorIdentifier": "urn:openproject-org:api:v3:errors:ResourceTypeMismatch",
        "message": "Expected resource of type 'User', but got a 'Status'.",
    }

Remove Watcher 

Remove watcher
/api/v3/work_packages/{work_package_id}/watchers/{id}

Removes the specified user from the list of watchers for the given work package.

If the request succeeds, the specified user is not watching the work package anymore.

Note: This might also be the case, if the specified user did not watch the work package prior to the request.

  • Parameters
  • work_package_id
    integer (required) Example: 1

    Work package id

    id
    integer (required) Example: 1

    User id

  • Response  204
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: delete work package watchers

    Note that you will only receive this error, if you are at least allowed to see the corresponding work package.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to remove watchers from this work package."
    }
  • Response  404
  • Returned in one of the following cases:

    Either the work package does not exist or the client does not have sufficient permissions to see it.

    Required permission: view work package

    Or the specified user does not exist at all.

    Note that you will effectively not be able to change the watchers of a work package without being able to see the work package.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified work package does not exist."
    }

Available relation candidates 

Lists work packages with which this work package can be in a relation. Only sound candidates are returned. For instance a work package cannot stand in relation to itself, and a work package that follows another cannot precede it.

Candidates can be filtered. Most commonly one will want to filter by subject. You can do this through the filters parameter which works just like the work package index.

For instance to find all work packages with “rollout” in their subject:

?filters=[{"subject":{"operator":"~","values":["rollout"]}}]

For convenience there is also a simple query parameter which is a shortcut for listing work packages whose ID or subject contain the given string.

While the endpoint does support the pageSize parameter to limit the number of results it does not support the offset parameter.

?query=112
Available relation candidates
/api/v3/work_packages/{id}/available_relation_candidates{?filters,query,type,pageSize}
  • Parameters
  • pageSize
    integer (optional) Example: 25

    Maximum number of candidates to list (default 10)

    filters
    string (optional) Example: [{ "status_id": { "operator": "o", "values": null }" }]

    JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint.

    query
    string (optional) Example: "rollout"

    Shortcut for filtering by ID or subject

    type
    string (optional) Example: "follows"

    Type of relation to find candidates for (default “relates”)

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/projects/14/work_packages"
        }
      },
      "total": 2,
      "count": 2,
      "_type": "Collection",
      "_embedded": {
        "elements": [
          {
            "_type": "WorkPackage",
            "_links": {
              "self": {
                "href": "/api/v3/work_packages/1"
              }
            },
            "id": 1,
            "subject": "Skipped other properties for brevity"
          },
          {
            "_type": "WorkPackage",
            "_links": {
              "self": {
                "href": "/api/v3/work_packages/2"
              }
            },
            "id": 2,
            "subject": "Skipped other properties for brevity"
          }
        ]
      }
    }

Available Watchers 

Available watchers
/api/v3/work_packages/{id}/available_watchers

Gets a list of users that are able to be watchers of the specified work package.

  • Parameters
  • id
    integer (required) Example: 1

    work package id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
        "_links": {
            "self": { "href": "/api/v3/work_packages/1/available_watchers" }
        },
        "total": 2,
        "count": 2,
        "_type": "Collection",
        "_embedded": {
          "elements": [
            {
                "_type": "User",
                "_links": {
                    "self": {
                        "href": "/api/v3/users/1",
                        "title": "John Sheppard - j.sheppard"
                    },
                    "lock": {
                        "href": "/api/v3/users/1/lock",
                        "title": "Set lock on j.sheppard"
                        "method": "POST"
                    },
                    "delete": {
                        "href": "/api/v3/users/1",
                        "title": "Delete j.sheppard"
                        "method": "DELETE"
                    }
                },
                "id": 1,
                "login": "j.sheppard",
                "firstName": "John",
                "lastName": "Sheppard",
                "email": "shep@mail.com",
                "avatar": "https://gravatar/avatar",
                "status": "active",
                "createdAt": "2014-05-21T08:51:20Z",
                "updatedAt": "2014-05-21T08:51:20Z"
            },
            {
                "_type": "User",
                "_links": {
                    "self": {
                        "href": "/api/v3/users/2",
                        "title": "Jim Sheppard - j.sheppard2"
                    },
                    "lock": {
                        "href": "/api/v3/users/2/lock",
                        "title": "Set lock on j.sheppard2"
                        "method": "POST"
                    },
                    "delete": {
                        "href": "/api/v3/users/2",
                        "title": "Delete j.sheppard2"
                        "method": "DELETE"
                    }
                },
                "id": 2,
                "login": "j.sheppard2",
                "firstName": "Jim",
                "lastName": "Sheppard",
                "email": "shep@mail.net",
                "avatar": "https://gravatar/avatar",
                "status": "active",
                "createdAt": "2014-05-21T08:51:20Z",
                "updatedAt": "2014-05-21T08:51:20Z"
            }]
        }
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: add work package watchers

    Note that you will only receive this error, if you are at least allowed to see the corresponding work package.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not authorized to access this resource."
    }
  • Response  404
  • Returned if the work package does not exist or the client does not have sufficient permissions to see it.

    Required permission: view work package

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified work package does not exist."
    }

Available Projects 

Available projects
/api/v3/work_packages/{id}/available_projects

Gets a list of projects that are available as projects to which the work package can be moved.

  • Parameters
  • id
    integer (required) Example: 1

    work package id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_links": {
        "self": {
          "href": "/api/v3/work_packages/5/available_projects"
        }
      },
      "_type": "Collection",
      "total": 2,
      "count": 2,
      "_embedded": {
        "elements": [
          {
            "_type": "Project",
            "_links": {
              "self": {
                "href": "/api/v3/projects/6",
                "title": "A project"
              },
              "createWorkPackage": {
                "href": "/api/v3/projects/6/work_packages/form",
                "method": "post"
              },
              "createWorkPackageImmediate": {
                "href": "/api/v3/projects/6/work_packages",
                "method": "post"
              },
              "categories": {
                "href": "/api/v3/projects/6/categories"
              },
              "versions": {
                "href": "/api/v3/projects/6/versions"
              }
            },
            "id": 6,
            "identifier": "a_project",
            "name": "A project",
            "description": "Eveniet molestias omnis quis aut qui eum adipisci. Atque aut aut in exercitationem adipisci amet. Nisi asperiores quia ratione veritatis enim exercitationem magnam. Aut fuga architecto adipisci nihil. Et repellat pariatur. Aliquam et sed perferendis nostrum quaerat. Fugit doloremque voluptatem.",
            "createdAt": "2015-07-06T13:28:14+00:00",
            "updatedAt": "2015-10-01T09:55:02+00:00",
            "type": "Customer Project"
          },
          {
            "_type": "Project",
            "_links": {
              "self": {
                "href": "/api/v3/projects/14",
                "title": "Another project"
              },
              "createWorkPackage": {
                "href": "/api/v3/projects/14/work_packages/form",
                "method": "post"
              },
              "createWorkPackageImmediate": {
                "href": "/api/v3/projects/14/work_packages",
                "method": "post"
              },
              "categories": {
                "href": "/api/v3/projects/14/categories"
              },
              "versions": {
                "href": "/api/v3/projects/14/versions"
              }
            },
            "id": 14,
            "identifier": "another_project",
            "name": "Another project",
            "description": "",
            "createdAt": "2016-02-29T12:50:20+00:00",
            "updatedAt": "2016-02-29T12:50:20+00:00",
            "type": null
          }]
        }
      }
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: edit work package

    Note that you will only receive this error, if you are at least allowed to see the corresponding work package.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not authorized to access this resource."
    }
  • Response  404
  • Returned if the work package does not exist or the client does not have sufficient permissions to see it.

    Required permission: view work package

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified work package does not exist."
    }

Revisions 

Revisions
/api/v3/work_packages/{id}/revisions

Gets a list of revisions that are linked to this work package, e.g., because it is referenced in the commit message of the revision. Only linked revisions from repositories are shown if the user has the view changesets permission in the defining project.

  • Parameters
  • id
    integer (required) Example: 1

    work package id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
        "_links": {
            "self": { "href": "/api/v3/work_packages/42/revisions" }
        },
        "total": 2,
        "count": 2,
        "_type": "Collection",
        "_embedded": {
          "elements": [
            {
                "_type": "Revision",
                "_links": {
                    "self": {
                        "href": "/api/v3/revisions/13",
                    },
                    "project": {
                        "href": "/api/v3/projects/1",
                        "title": "A Test Project
                    },
                    "author": {
                        "href": "/api/v3/users/1",
                        "title": "John Sheppard - j.sheppard"
                    },
                    "showRevision": {
                        "href": "/projects/identifier/repository/revision/11f4b07"
                    }
                },
                "id": 13,
                "identifier": "11f4b07dff4f4ce9548a52b7d002daca7cd63ec6",
                "formattedIdentifier": "11f4b07",
                "authorName": "John Sheppard",
                "message": {
                    "format": "plain",
                    "raw": "This revision provides new features\n\nAn elaborate description",
                    "html": "<p>This revision provides new features<br/><br/>An elaborate description</p>"
                },
                "createdAt": "2015-07-21T13:36:59Z",
            },
            {
                "_type": "Revision",
                "_links": {
                    "self": {
                        "href": "/api/v3/revisions/14",
                    },
                    "project": {
                        "href": "/api/v3/projects/1",
                        "title": "A Test Project
                    },
                    "author": {
                        "href": "/api/v3/users/2",
                        "title": "Jim Sheppard - j.sheppard"
                    }
                    "showRevision": {
                        "href": "/projects/identifier/repository/revision/029ed72a"
                    }
                },
                "id": 13,
                "identifier": "029ed72a3b7b7c4ab332b1f6eaa6576e7c946059",
                "formattedIdentifier": "029ed72a",
                "authorName": "j1msheppard",
                "message": {
                    "format": "plain",
                    "raw": "This revision fixes some stuff\n\nMore information here",
                    "html": "<p>This revision fixes some stuff<br/><br/>More information here</p>"
                },
                "createdAt": "2015-06-30T08:47:00Z",
            }]
        }
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: view work packages for the project the work package is contained in.

    Note that you will only receive this error, if you are at least allowed to see the corresponding work package.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to see linked revisions for this work package."
    }
  • Response  404
  • Returned if the work package does not exist or the client does not have sufficient permissions to see it.

    Required permission: view work package

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified work project does not exist."
    }

Work Package activities 

List work package activities
/api/v3/work_packages/{id}/activities{?notify}
  • Parameters
  • id
    integer (required) Example: 1

    Work package id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Activity::Comment",
      "_links": {
        "self": {
          "href": "/api/v3/activity/1",
          "title": "Priority changed from High to Low"
        },
        "workPackage": {
          "href": "/api/v3/work_packages/1",
          "title": "quis numquam qui voluptatum quia praesentium blanditiis nisi"
        },
        "user": {
          "href": "/api/v3/users/1",
          "title": "John Sheppard - admin"
        }
      },
      "id": 1,
      "details": [
        {
          "format": "textile",
          "raw": "Lorem ipsum dolor sit amet.",
          "html": "<p>Lorem ipsum dolor sit amet.</p>"
        }
      ],
      "comment": {
        "format": "textile",
        "raw": "Lorem ipsum dolor sit amet.",
        "html": "<p>Lorem ipsum dolor sit amet.</p>"
      },
      "createdAt": "2014-05-21T08:51:20Z",
      "version": 31
    }
  • Response  404
  • Returned if the work package does not exist or the client does not have sufficient permissions to see it.

    Required permission: view work package

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified work package does not exist."
    }
Comment work package
/api/v3/work_packages/{id}/activities{?notify}

Creates an activity for the selected work package and, on success, returns the updated activity.

  • Parameters
  • id
    integer (required) Example: 1

    Work package id

    notify
    boolean (optional) Default: true Example: false

    Indicates whether change notifications (e.g. via E-Mail) should be sent. Note that this controls notifications for all users interested in changes to the work package (e.g. watchers, author and assignee), not just the current user.

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
      "comment": {
        "raw": "I think this is awesome!"
      }
    }
  • Response  201
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Activity::Comment",
      "_links": {
        "self": {
          "href": "/api/v3/activity/1",
          "title": "Priority changed from High to Low"
        },
        "workPackage": {
          "href": "/api/v3/work_packages/1",
          "title": "quis numquam qui voluptatum quia praesentium blanditiis nisi"
        },
        "user": {
          "href": "/api/v3/users/1",
          "title": "John Sheppard - admin"
        }
      },
      "id": 1,
      "details": [
        {
          "format": "textile",
          "raw": "Lorem ipsum dolor sit amet.",
          "html": "<p>Lorem ipsum dolor sit amet.</p>"
        }
      ],
      "comment": {
        "format": "textile",
        "raw": "Lorem ipsum dolor sit amet.",
        "html": "<p>Lorem ipsum dolor sit amet.</p>"
      },
      "createdAt": "2014-05-21T08:51:20Z",
      "version": 31
    }
  • Response  400
  • Occurs when the client did not send a valid JSON object in the request body.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
      "message": "The request body was not a single JSON object."
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: create journals

    Note that you will only receive this error, if you are at least allowed to see the corresponding work package.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to create a comment here."
    }
  • Response  404
  • Returned if the work package does not exist or the client does not have sufficient permissions to see it.

    Required permission: view work package

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified work package does not exist."
    }

Available Assignees 

Available assignees
/api/v3/projects/{project_id}/work_packages/available_assignees

Gets a list of users that can be assigned to work packages in the given project.

  • Parameters
  • project_id
    integer (required) Example: 1

    Project id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
        "_links": {
            "self": { "href": "/api/v3/projects/42/work_packages/available_assignees" }
        },
        "total": 2,
        "count": 2,
        "_type": "Collection",
        "_embedded": {
          "elements": [
            {
                "_type": "User",
                "_links": {
                    "self": {
                        "href": "/api/v3/users/1",
                        "title": "John Sheppard - j.sheppard"
                    },
                    "lock": {
                        "href": "/api/v3/users/1/lock",
                        "title": "Set lock on j.sheppard"
                        "method": "POST"
                    },
                    "delete": {
                        "href": "/api/v3/users/1",
                        "title": "Delete j.sheppard"
                        "method": "DELETE"
                    }
                },
                "id": 1,
                "login": "j.sheppard",
                "firstName": "John",
                "lastName": "Sheppard",
                "email": "shep@mail.com",
                "avatar": "https://gravatar/avatar",
                "status": "active",
                "createdAt": "2014-05-21T08:51:20Z",
                "updatedAt": "2014-05-21T08:51:20Z"
            },
            {
                "_type": "User",
                "_links": {
                    "self": {
                        "href": "/api/v3/users/2",
                        "title": "Jim Sheppard - j.sheppard2"
                    },
                    "lock": {
                        "href": "/api/v3/users/2/lock",
                        "title": "Set lock on j.sheppard2"
                        "method": "POST"
                    },
                    "delete": {
                        "href": "/api/v3/users/2",
                        "title": "Delete j.sheppard2"
                        "method": "DELETE"
                    }
                },
                "id": 2,
                "login": "j.sheppard2",
                "firstName": "Jim",
                "lastName": "Sheppard",
                "email": "shep@mail.net",
                "avatar": "https://gravatar/avatar",
                "status": "active",
                "createdAt": "2014-05-21T08:51:20Z",
                "updatedAt": "2014-05-21T08:51:20Z"
            }]
        }
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: view work packages

    Note that you will only receive this error, if you are at least allowed to see the corresponding project.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to see the assignable users for this project."
    }
  • Response  404
  • Returned if the project does not exist or the client does not have sufficient permissions to see it.

    Required permission: view project

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified project does not exist."
    }

Available Responsibles 

Available responsibles
/api/v3/projects/{project_id}/work_packages/available_responsibles

Gets a list of users that can be assigned as the responsible of a work package in the given project.

  • Parameters
  • project_id
    integer (required) Example: 1

    Project id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
        "_links": {
            "self": { "href": "/api/v3/projects/42/work_packages/available_responsibles" }
        },
        "total": 2,
        "count": 2,
        "_type": "Collection",
        "_embedded": {
          "elements": [
            {
                "_type": "User",
                "_links": {
                    "self": {
                        "href": "/api/v3/users/1",
                        "title": "John Sheppard - j.sheppard"
                    },
                    "lock": {
                        "href": "/api/v3/users/1/lock",
                        "title": "Set lock on j.sheppard"
                        "method": "POST"
                    },
                    "delete": {
                        "href": "/api/v3/users/1",
                        "title": "Delete j.sheppard"
                        "method": "DELETE"
                    }
                },
                "id": 1,
                "login": "j.sheppard",
                "firstName": "John",
                "lastName": "Sheppard",
                "email": "shep@mail.com",
                "avatar": "https://gravatar/avatar",
                "status": "active",
                "createdAt": "2014-05-21T08:51:20Z",
                "updatedAt": "2014-05-21T08:51:20Z"
            },
            {
                "_type": "User",
                "_links": {
                    "self": {
                        "href": "/api/v3/users/2",
                        "title": "Jim Sheppard - j.sheppard2"
                    },
                    "lock": {
                        "href": "/api/v3/users/2/lock",
                        "title": "Set lock on j.sheppard2"
                        "method": "POST"
                    },
                    "delete": {
                        "href": "/api/v3/users/2",
                        "title": "Delete j.sheppard2"
                        "method": "DELETE"
                    }
                },
                "id": 2,
                "login": "j.sheppard2",
                "firstName": "Jim",
                "lastName": "Sheppard",
                "email": "shep@mail.net",
                "avatar": "https://gravatar/avatar",
                "status": "active",
                "createdAt": "2014-05-21T08:51:20Z",
                "updatedAt": "2014-05-21T08:51:20Z"
            }]
        }
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: view work packages

    Note that you will only receive this error, if you are at least allowed to see the corresponding project.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to see the users available as responsible for this project."
    }
  • Response  404
  • Returned if the project does not exist or the client does not have sufficient permissions to see it.

    Required permission: view project

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified project does not exist."
    }

Note:

You can propose a change to this OpenProject API documentation by creating a pull request on GitHub.

Last Update: January 11 2017 17:01:11.