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 |
Attachments
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.
- RequestToggle details
Headers
Content-Type: multipart/form-data; boundary=boundary-delimiter
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
Toggle details 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" }, "staticDownloadLocation": { "href": "/api/v3/attachments/1/download" } "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", "64c26a8403cd796ea4cf913cda2ee4a9": }, "createdAt": "2014-05-21T08:51:20Z" }
- Response
400
Toggle details 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
Toggle details 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)
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
422
Toggle details 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)." }
-
Attachment
- Parameters
- id
integer
(required) Example: 1Attachment id
- Response
200
Toggle details 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" }, "staticDownloadLocation": { "href": "/api/v3/attachments/1/download" } "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", "64c26a8403cd796ea4cf913cda2ee4a9": }, "createdAt": "2014-05-21T08:51:20Z" }
- Response
404
Toggle details 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.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The specified attachment does not exist." }
Permanently deletes the specified attachment.
- Parameters
- id
integer
(required) Example: 1Attachment id
- Response
204
Toggle details 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
Toggle details 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.
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
Toggle details 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.
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 post
- Parameters
- id
integer
(required) Example: 1ID of the post whose attachments will be listed
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_type": "Collection", "total": 1, "count": 1, "_embedded": { "elements": [ { "_type": "Attachment", "id": 376, "fileName": "some.gif", "fileSize": 3521772, "description": { "format": "plain", "raw": "", "html": "" }, "contentType": "image/gif", "digest": { "algorithm": "md5", "hash": "7ac9c97ef73d47127f590788b84c0c1c" }, "createdAt": "2018-06-01T07:24:19Z", "_links": { "self": { "href": "/api/v3/attachments/376", "title": "200.gif" }, "author": { "href": "/api/v3/users/1", "title": "OpenProject Admin" }, "container": { "href": "/api/v3/posts/72", "title": "wiki" }, "downloadLocation": { "href": "/api/v3/attachments/376/content" }, "delete": { "href": "/api/v3/attachments/376", "method": "delete" } } } ] }, "_links": { "self": { "href": "/api/v3/posts/72/attachments" } } }
- Response
404
Toggle details 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.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The requested resource could not be found." }
Adds an attachment with the post as it’s container.
See the general specification for uploading attachments for details.
- Parameters
- id
integer
(required) Example: 1ID of the post to receive the attachment
- RequestToggle details
Headers
Content-Type: multipart/form-data; boundary=boundary-delimiter
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
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_embedded": { "author": { "_type": "User", "id": 1, "name": "OpenProject Admin", "createdAt": "2015-03-20T12:56:52Z", "updatedAt": "2018-05-29T13:57:44Z", "login": "admin", "admin": true, "firstName": "OpenProject", "lastName": "Admin", "email": null, "avatar": "", "status": "active", "identityUrl": null, "_links": { "self": { "href": "/api/v3/users/1", "title": "OpenProject Admin" }, "showUser": { "href": "/users/1", "type": "text/html" }, "updateImmediately": { "href": "/api/v3/users/1", "title": "Update admin", "method": "patch" }, "lock": { "href": "/api/v3/users/1/lock", "title": "Set lock on admin", "method": "post" } } }, "container": { "_type": "Post", "id": 150, "subject": "sfsdfsdfsdfsdf", "_links": { "self": { "href": "/api/v3/posts/150" }, "attachments": { "href": "/api/v3/posts/150/attachments" }, "addAttachment": { "href": "/api/v3/posts/150/attachments", "method": "post" }, "project": { "href": "/api/v3/projects/12", "title": "Demo project" } } } }, "_type": "Attachment", "id": 377, "fileName": "some.gif", "fileSize": 3521772, "description": { "format": "plain", "raw": "", "html": "" }, "contentType": "image/gif", "digest": { "algorithm": "md5", "hash": "7ac9c97ef73d47127f590788b84c0c1c" }, "createdAt": "2018-06-01T07:53:36Z", "_links": { "self": { "href": "/api/v3/attachments/377", "title": "200.gif" }, "author": { "href": "/api/v3/users/1", "title": "OpenProject Admin" }, "container": { "href": "/api/v3/posts/150", "title": "sfsdfsdfsdfsdf" }, "downloadLocation": { "href": "/api/v3/attachments/377/content" }, "delete": { "href": "/api/v3/attachments/377", "method": "delete" } } }
- Response
400
Toggle details 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
Toggle details 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
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
Toggle details 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.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The requested resource could not be found." }
- Response
422
Toggle details 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)." }
-
Attachments by wiki page
- Parameters
- id
integer
(required) Example: 1ID of the wiki page whose attachments will be listed
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_type": "Collection", "total": 1, "count": 1, "_embedded": { "elements": [ { "_type": "Attachment", "id": 376, "fileName": "some.gif", "fileSize": 3521772, "description": { "format": "plain", "raw": "", "html": "" }, "contentType": "image/gif", "digest": { "algorithm": "md5", "hash": "7ac9c97ef73d47127f590788b84c0c1c" }, "createdAt": "2018-06-01T07:24:19Z", "_links": { "self": { "href": "/api/v3/attachments/376", "title": "200.gif" }, "author": { "href": "/api/v3/users/1", "title": "OpenProject Admin" }, "container": { "href": "/api/v3/wiki_pages/72", "title": "wiki" }, "downloadLocation": { "href": "/api/v3/attachments/376/content" }, "delete": { "href": "/api/v3/attachments/376", "method": "delete" } } } ] }, "_links": { "self": { "href": "/api/v3/wiki_pages/72/attachments" } } }
- Response
404
Toggle details 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.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The requested resource could not be found." }
Adds an attachment with the wiki page as it’s container.
See the general specification for uploading attachments for details.
- Parameters
- id
integer
(required) Example: 1ID of the wiki page to receive the attachment
- RequestToggle details
Headers
Content-Type: multipart/form-data; boundary=boundary-delimiter
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
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_embedded": { "author": { "_type": "User", "id": 1, "name": "OpenProject Admin", "createdAt": "2015-03-20T12:56:52Z", "updatedAt": "2018-05-29T13:57:44Z", "login": "admin", "admin": true, "firstName": "OpenProject", "lastName": "Admin", "email": null, "avatar": "", "status": "active", "identityUrl": null, "_links": { "self": { "href": "/api/v3/users/1", "title": "OpenProject Admin" }, "showUser": { "href": "/users/1", "type": "text/html" }, "updateImmediately": { "href": "/api/v3/users/1", "title": "Update admin", "method": "patch" }, "lock": { "href": "/api/v3/users/1/lock", "title": "Set lock on admin", "method": "post" } } }, "container": { "_type": "WikiPage", "id": 72, "title": "wiki", "_links": { "self": { "href": "/api/v3/wiki_pages/72" }, "attachments": { "href": "/api/v3/wiki_pages/72/attachments" }, "addAttachment": { "href": "/api/v3/wiki_pages/72/attachments", "method": "post" }, "project": { "href": "/api/v3/projects/12", "title": "Demo project" } } } }, "_type": "Attachment", "id": 376, "fileName": "some.gif", "fileSize": 3521772, "description": { "format": "plain", "raw": "", "html": "" }, "contentType": "image/gif", "digest": { "algorithm": "md5", "hash": "7ac9c97ef73d47127f590788b84c0c1c" }, "createdAt": "2018-06-01T07:24:19Z", "_links": { "self": { "href": "/api/v3/attachments/376", "title": "200.gif" }, "author": { "href": "/api/v3/users/1", "title": "OpenProject Admin" }, "container": { "href": "/api/v3/wiki_pages/72", "title": "wiki" }, "downloadLocation": { "href": "/api/v3/attachments/376/content" }, "delete": { "href": "/api/v3/attachments/376", "method": "delete" } } }
- Response
400
Toggle details 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
Toggle details 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
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
Toggle details 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.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The requested resource could not be found." }
- Response
422
Toggle details 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)." }
-
Attachments by work package
- Parameters
- id
integer
(required) Example: 1ID of the work package whose attachments will be listed
- Response
200
Toggle details 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
Toggle details 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." }
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: 1ID of the work package to receive the attachment
- RequestToggle details
Headers
Content-Type: multipart/form-data; boundary=boundary-delimiter
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
Toggle details 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" }, "staticDownloadLocation": { "href": "/api/v3/attachments/1/download" } "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", "64c26a8403cd796ea4cf913cda2ee4a9": }, "createdAt": "2014-05-21T08:51:20Z" }
- Response
400
Toggle details 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
Toggle details 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
Toggle details 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
Toggle details 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)." }
-
Help and feedback
If you did not find what you were looking for
If you need help from the community or want to support others
If you are eligible for professional support and have more questions
REQUEST SUPPORT
If you find an easily fixable error or need for improvement in the documentation for the stable release
If you would like to suggest bigger updates or improvements to this documentation
If you want to contribute to translate this documentation to another language
If there's something you don't like or understand about this feature
If you want to propose a new feature that OpenProject does not offer yet
To further help OpenProject to shape and test new features
To view OpenProject premium features and pricing
If you want to try all premium features in the OpenProject Cloud Edition 14 days for free
If you want to try all premium features in your on premise Community installation 14 days for free