API: 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

Link Description Condition
delete Deletes this attachment Permission: edit on attachment container or being the author for attachments without container

Linked Properties

Link Description Type Constraints Supported operations
self This attachment Attachment not null READ
container The object (e.g. WorkPackage) housing the attachment Anything not null READ
author The user who uploaded the attachment User not null READ
downloadLocation Direct download link to the attachment - not null READ

Local Properties

Property Description Type Constraints Supported operations
id Attachment’s id Integer x > 0 READ
title The name of the file String not null READ
fileName The name of the uploaded file String not null READ
fileSize The size of the uploaded file in Bytes Integer x >= 0 READ
description A user provided description of the file Formattable not null READ
contentType The files MIME-Type as determined by the server String not null READ
digest A checksum for the files content Digest not null READ
createdAt Time of creation DateTime not null READ

Methods

Create attachment

Clients can create attachments without a container first and attach them later on. This is useful if the container does not exist at the time the attachment is uploaded. After the upload, the client can then claim such containerless attachments for any resource eligible (e.g. WorkPackage) on subsequent requests. The upload and the claiming must be done for the same user account. Attachments uploaded by another user cannot be claimed and once claimed for a resource, they cannot be claimed by another.

The upload request must be 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, although it will be ignored. Instead the fileName inside the JSON of the metadata part will be used.

No parameters

200

OK

AttachmentModel
{
  "type": "object",
  "required": [
    "title",
    "fileName",
    "description",
    "contentType",
    "digest",
    "createdAt"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "Attachment's id",
      "minimum": 1
    },
    "title": {
      "type": "string",
      "description": "The name of the file"
    },
    "fileName": {
      "type": "string",
      "description": "The name of the uploaded file"
    },
    "fileSize": {
      "type": "integer",
      "description": "The size of the uploaded file in Bytes",
      "minimum": 0
    },
    "description": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Formattable"
        },
        {
          "description": "A user provided description of the file"
        }
      ]
    },
    "contentType": {
      "type": "string",
      "description": "The files MIME-Type as determined by the server"
    },
    "digest": {
      "type": "string",
      "description": "A checksum for the files content"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of creation"
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "container",
        "author",
        "downloadLocation"
      ],
      "properties": {
        "delete": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Deletes this attachment\n\n# Conditions\n\n**Permission**: edit on attachment container or being the author for attachments without container"
            }
          ]
        },
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This attachment\n\n**Resource**: Attachment"
            }
          ]
        },
        "container": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The object (e.g. WorkPackage) housing the attachment\n\n**Resource**: Anything"
            }
          ]
        },
        "author": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The user who uploaded the attachment\n\n**Resource**: User"
            }
          ]
        },
        "downloadLocation": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Direct download link to the attachment\n\n**Resource**: -"
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "Attachment",
    "_links": {
      "self": {
        "href": "/api/v3/attachments/1"
      },
      "container": {
        "href": "/api/v3/work_packages/1"
      },
      "author": {
        "href": "/api/v3/users/1"
      },
      "staticDownloadLocation": {
        "href": "/api/v3/attachments/1/content"
      },
      "downloadLocation": {
        "href": "/some/remote/aws/url/image.png"
      }
    },
    "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",
      "hash": "64c26a8403cd796ea4cf913cda2ee4a9"
    },
    "createdAt": "2014-05-21T08:51:20.396Z"
  }
}

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

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request could not be parsed as JSON."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: At least one permission in any project: edit work package, add work package, edit messages, edit wiki pages (plugins might extend this list)

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to delete this attachment."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"
{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

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

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "File is too large (maximum size is 5242880 Bytes)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

View attachment

id
integer

required path

Attachment id

Example:
1

200

OK

AttachmentModel
{
  "type": "object",
  "required": [
    "title",
    "fileName",
    "description",
    "contentType",
    "digest",
    "createdAt"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "Attachment's id",
      "minimum": 1
    },
    "title": {
      "type": "string",
      "description": "The name of the file"
    },
    "fileName": {
      "type": "string",
      "description": "The name of the uploaded file"
    },
    "fileSize": {
      "type": "integer",
      "description": "The size of the uploaded file in Bytes",
      "minimum": 0
    },
    "description": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Formattable"
        },
        {
          "description": "A user provided description of the file"
        }
      ]
    },
    "contentType": {
      "type": "string",
      "description": "The files MIME-Type as determined by the server"
    },
    "digest": {
      "type": "string",
      "description": "A checksum for the files content"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of creation"
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "container",
        "author",
        "downloadLocation"
      ],
      "properties": {
        "delete": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Deletes this attachment\n\n# Conditions\n\n**Permission**: edit on attachment container or being the author for attachments without container"
            }
          ]
        },
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This attachment\n\n**Resource**: Attachment"
            }
          ]
        },
        "container": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The object (e.g. WorkPackage) housing the attachment\n\n**Resource**: Anything"
            }
          ]
        },
        "author": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The user who uploaded the attachment\n\n**Resource**: User"
            }
          ]
        },
        "downloadLocation": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Direct download link to the attachment\n\n**Resource**: -"
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "Attachment",
    "_links": {
      "self": {
        "href": "/api/v3/attachments/1"
      },
      "container": {
        "href": "/api/v3/work_packages/1"
      },
      "author": {
        "href": "/api/v3/users/1"
      },
      "staticDownloadLocation": {
        "href": "/api/v3/attachments/1/content"
      },
      "downloadLocation": {
        "href": "/some/remote/aws/url/image.png"
      }
    },
    "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",
      "hash": "64c26a8403cd796ea4cf913cda2ee4a9"
    },
    "createdAt": "2014-05-21T08:51:20.396Z"
  }
}

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 or being the author for attachments without container

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.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified attachment does not exist."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Delete attachment

Permanently deletes the specified attachment.

id
integer

required path

Attachment id

Example:
1

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.

403

Returned if the client does not have sufficient permissions.

Required permission: edit permission for the container of the attachment or being the author for attachments without container

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

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to delete this attachment."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

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 or being the author for attachments without container

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.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified attachment does not exist."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"
{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

List attachments by post

id
integer

required path

ID of the post whose attachments will be listed

Example:
1

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "author": {
            "href": "/api/v3/users/1",
            "title": "OpenProject Admin"
          },
          "container": {
            "href": "/api/v3/posts/72",
            "title": "wiki"
          },
          "delete": {
            "href": "/api/v3/attachments/376",
            "method": "delete"
          },
          "downloadLocation": {
            "href": "/api/v3/attachments/376/content"
          },
          "self": {
            "href": "/api/v3/attachments/376",
            "title": "200.gif"
          }
        },
        "_type": "Attachment",
        "contentType": "image/gif",
        "createdAt": "2018-06-01T07:24:19.706Z",
        "description": {
          "format": "plain",
          "html": "",
          "raw": ""
        },
        "digest": {
          "algorithm": "md5",
          "hash": "7ac9c97ef73d47127f590788b84c0c1c"
        },
        "fileName": "some.gif",
        "fileSize": 3521772,
        "id": 376
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/posts/72/attachments"
    }
  },
  "_type": "Collection",
  "count": 1,
  "total": 1
}
Attachments_Model
{
  "allOf": [
    {
      "$ref": "#/components/schemas/CollectionModel"
    },
    {
      "type": "object",
      "required": [
        "_links",
        "_embedded"
      ],
      "properties": {
        "_links": {
          "type": "object",
          "required": [
            "self"
          ],
          "properties": {
            "self": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "The attachments collection\n\n**Resource**: AttachmentsCollection",
                  "readOnly": true
                }
              ]
            }
          }
        },
        "_embedded": {
          "type": "object",
          "properties": {
            "elements": {
              "type": "array",
              "readOnly": true,
              "items": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/AttachmentModel"
                  },
                  {
                    "description": "Collection of Attachments"
                  }
                ]
              }
            }
          }
        }
      }
    }
  ]
}

404

Returned if the post does not exist or the client does not have sufficient permissions to see it.

Required permission: view messages

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

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Add attachment to post

Adds an attachment with the post as it’s container.

id
integer

required path

ID of the post to receive the attachment

Example:
1

200

OK

{
  "_embedded": {
    "author": {
      "_links": {
        "lock": {
          "href": "/api/v3/users/1/lock",
          "method": "post",
          "title": "Set lock on admin"
        },
        "self": {
          "href": "/api/v3/users/1",
          "title": "OpenProject Admin"
        },
        "showUser": {
          "href": "/users/1",
          "type": "text/html"
        },
        "updateImmediately": {
          "href": "/api/v3/users/1",
          "method": "patch",
          "title": "Update admin"
        }
      },
      "_type": "User",
      "admin": true,
      "avatar": "",
      "createdAt": "2015-03-20T12:56:52.850Z",
      "email": null,
      "firstName": "OpenProject",
      "id": 1,
      "identityUrl": null,
      "lastName": "Admin",
      "login": "admin",
      "name": "OpenProject Admin",
      "status": "active",
      "updatedAt": "2018-05-29T13:57:44.604Z"
    },
    "container": {
      "_links": {
        "addAttachment": {
          "href": "/api/v3/posts/150/attachments",
          "method": "post"
        },
        "attachments": {
          "href": "/api/v3/posts/150/attachments"
        },
        "project": {
          "href": "/api/v3/projects/12",
          "title": "Demo project"
        },
        "self": {
          "href": "/api/v3/posts/150"
        }
      },
      "_type": "Post",
      "id": 150,
      "subject": "sfsdfsdfsdfsdf"
    }
  },
  "_links": {
    "author": {
      "href": "/api/v3/users/1",
      "title": "OpenProject Admin"
    },
    "container": {
      "href": "/api/v3/posts/150",
      "title": "sfsdfsdfsdfsdf"
    },
    "delete": {
      "href": "/api/v3/attachments/377",
      "method": "delete"
    },
    "downloadLocation": {
      "href": "/api/v3/attachments/377/content"
    },
    "self": {
      "href": "/api/v3/attachments/377",
      "title": "200.gif"
    }
  },
  "_type": "Attachment",
  "contentType": "image/gif",
  "createdAt": "2018-06-01T07:53:36.831Z",
  "description": {
    "format": "plain",
    "html": "",
    "raw": ""
  },
  "digest": {
    "algorithm": "md5",
    "hash": "7ac9c97ef73d47127f590788b84c0c1c"
  },
  "fileName": "some.gif",
  "fileSize": 3521772,
  "id": 377
}

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

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request could not be parsed as JSON."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: edit messages

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

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to delete this attachment."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the post does not exist or the client does not have sufficient permissions to see it.

Required permission: view messages

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

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"
{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

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

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "File is too large (maximum size is 5242880 Bytes)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

List attachments by wiki page

id
integer

required path

ID of the wiki page whose attachments will be listed

Example:
1

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "author": {
            "href": "/api/v3/users/1",
            "title": "OpenProject Admin"
          },
          "container": {
            "href": "/api/v3/wiki_pages/72",
            "title": "wiki"
          },
          "delete": {
            "href": "/api/v3/attachments/376",
            "method": "delete"
          },
          "downloadLocation": {
            "href": "/api/v3/attachments/376/content"
          },
          "self": {
            "href": "/api/v3/attachments/376",
            "title": "200.gif"
          }
        },
        "_type": "Attachment",
        "contentType": "image/gif",
        "createdAt": "2018-06-01T07:24:19.896Z",
        "description": {
          "format": "plain",
          "html": "",
          "raw": ""
        },
        "digest": {
          "algorithm": "md5",
          "hash": "7ac9c97ef73d47127f590788b84c0c1c"
        },
        "fileName": "some.gif",
        "fileSize": 3521772,
        "id": 376
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/wiki_pages/72/attachments"
    }
  },
  "_type": "Collection",
  "count": 1,
  "total": 1
}
Attachments_Model
{
  "allOf": [
    {
      "$ref": "#/components/schemas/CollectionModel"
    },
    {
      "type": "object",
      "required": [
        "_links",
        "_embedded"
      ],
      "properties": {
        "_links": {
          "type": "object",
          "required": [
            "self"
          ],
          "properties": {
            "self": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "The attachments collection\n\n**Resource**: AttachmentsCollection",
                  "readOnly": true
                }
              ]
            }
          }
        },
        "_embedded": {
          "type": "object",
          "properties": {
            "elements": {
              "type": "array",
              "readOnly": true,
              "items": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/AttachmentModel"
                  },
                  {
                    "description": "Collection of Attachments"
                  }
                ]
              }
            }
          }
        }
      }
    }
  ]
}

404

Returned if the wiki page does not exist or the client does not have sufficient permissions to see it.

Required permission: view wiki pages

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.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Add attachment to wiki page

Adds an attachment with the wiki page as it’s container.

id
integer

required path

ID of the wiki page to receive the attachment

Example:
1

200

OK

{
  "_embedded": {
    "author": {
      "_links": {
        "lock": {
          "href": "/api/v3/users/1/lock",
          "method": "post",
          "title": "Set lock on admin"
        },
        "self": {
          "href": "/api/v3/users/1",
          "title": "OpenProject Admin"
        },
        "showUser": {
          "href": "/users/1",
          "type": "text/html"
        },
        "updateImmediately": {
          "href": "/api/v3/users/1",
          "method": "patch",
          "title": "Update admin"
        }
      },
      "_type": "User",
      "admin": true,
      "avatar": "",
      "createdAt": "2015-03-20T12:56:52.343Z",
      "email": null,
      "firstName": "OpenProject",
      "id": 1,
      "identityUrl": null,
      "lastName": "Admin",
      "login": "admin",
      "name": "OpenProject Admin",
      "status": "active",
      "updatedAt": "2018-05-29T13:57:44.662Z"
    },
    "container": {
      "_links": {
        "addAttachment": {
          "href": "/api/v3/wiki_pages/72/attachments",
          "method": "post"
        },
        "attachments": {
          "href": "/api/v3/wiki_pages/72/attachments"
        },
        "project": {
          "href": "/api/v3/projects/12",
          "title": "Demo project"
        },
        "self": {
          "href": "/api/v3/wiki_pages/72"
        }
      },
      "_type": "WikiPage",
      "id": 72,
      "title": "wiki"
    }
  },
  "_links": {
    "author": {
      "href": "/api/v3/users/1",
      "title": "OpenProject Admin"
    },
    "container": {
      "href": "/api/v3/wiki_pages/72",
      "title": "wiki"
    },
    "delete": {
      "href": "/api/v3/attachments/376",
      "method": "delete"
    },
    "downloadLocation": {
      "href": "/api/v3/attachments/376/content"
    },
    "self": {
      "href": "/api/v3/attachments/376",
      "title": "200.gif"
    }
  },
  "_type": "Attachment",
  "contentType": "image/gif",
  "createdAt": "2018-06-01T07:24:19.896Z",
  "description": {
    "format": "plain",
    "html": "",
    "raw": ""
  },
  "digest": {
    "algorithm": "md5",
    "hash": "7ac9c97ef73d47127f590788b84c0c1c"
  },
  "fileName": "some.gif",
  "fileSize": 3521772,
  "id": 376
}

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

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request could not be parsed as JSON."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: edit wiki pages

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

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to delete this attachment."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the wiki page does not exist or the client does not have sufficient permissions to see it.

Required permission: view wiki pages

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

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"
{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

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

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "File is too large (maximum size is 5242880 Bytes)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

List attachments by work package

id
integer

required path

ID of the work package whose attachments will be listed

Example:
1

200

OK

Attachments_Model
{
  "allOf": [
    {
      "$ref": "#/components/schemas/CollectionModel"
    },
    {
      "type": "object",
      "required": [
        "_links",
        "_embedded"
      ],
      "properties": {
        "_links": {
          "type": "object",
          "required": [
            "self"
          ],
          "properties": {
            "self": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "The attachments collection\n\n**Resource**: AttachmentsCollection",
                  "readOnly": true
                }
              ]
            }
          }
        },
        "_embedded": {
          "type": "object",
          "properties": {
            "elements": {
              "type": "array",
              "readOnly": true,
              "items": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/AttachmentModel"
                  },
                  {
                    "description": "Collection of Attachments"
                  }
                ]
              }
            }
          }
        }
      }
    }
  ]
}

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.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified work package does not exist."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Create work package attachment

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.

id
integer

required path

ID of the work package to receive the attachment

Example:
1

200

OK

AttachmentModel
{
  "type": "object",
  "required": [
    "title",
    "fileName",
    "description",
    "contentType",
    "digest",
    "createdAt"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "Attachment's id",
      "minimum": 1
    },
    "title": {
      "type": "string",
      "description": "The name of the file"
    },
    "fileName": {
      "type": "string",
      "description": "The name of the uploaded file"
    },
    "fileSize": {
      "type": "integer",
      "description": "The size of the uploaded file in Bytes",
      "minimum": 0
    },
    "description": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Formattable"
        },
        {
          "description": "A user provided description of the file"
        }
      ]
    },
    "contentType": {
      "type": "string",
      "description": "The files MIME-Type as determined by the server"
    },
    "digest": {
      "type": "string",
      "description": "A checksum for the files content"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of creation"
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "container",
        "author",
        "downloadLocation"
      ],
      "properties": {
        "delete": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Deletes this attachment\n\n# Conditions\n\n**Permission**: edit on attachment container or being the author for attachments without container"
            }
          ]
        },
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This attachment\n\n**Resource**: Attachment"
            }
          ]
        },
        "container": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The object (e.g. WorkPackage) housing the attachment\n\n**Resource**: Anything"
            }
          ]
        },
        "author": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The user who uploaded the attachment\n\n**Resource**: User"
            }
          ]
        },
        "downloadLocation": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Direct download link to the attachment\n\n**Resource**: -"
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "Attachment",
    "_links": {
      "self": {
        "href": "/api/v3/attachments/1"
      },
      "container": {
        "href": "/api/v3/work_packages/1"
      },
      "author": {
        "href": "/api/v3/users/1"
      },
      "staticDownloadLocation": {
        "href": "/api/v3/attachments/1/content"
      },
      "downloadLocation": {
        "href": "/some/remote/aws/url/image.png"
      }
    },
    "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",
      "hash": "64c26a8403cd796ea4cf913cda2ee4a9"
    },
    "createdAt": "2014-05-21T08:51:20.396Z"
  }
}

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

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request could not be parsed as JSON."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: 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.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to delete this attachment."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

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.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified work package does not exist."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"
{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

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

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "File is too large (maximum size is 5242880 Bytes)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}