API: File links
TBD
Methods
Gets a file link.
Gets a single file link resource of a work package.
id
integer
required path
File link id
Example:
42
200
OK
Content-Type: application/hal+json
FileLinkReadModel
{
"type": "object",
"required": [
"id",
"_type",
"originData",
"_links"
],
"properties": {
"id": {
"type": "integer",
"description": "File link id"
},
"_type": {
"type": "string",
"enum": [
"FileLink"
]
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Time of creation"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Time of the most recent change to the file link"
},
"originData": {
"$ref": "#/components/schemas/FileLinkOriginDataModel"
},
"_embedded": {
"type": "object",
"required": [
"storage",
"container"
],
"properties": {
"storage": {
"$ref": "#/components/schemas/StorageModel"
},
"container": {
"$ref": "#/components/schemas/Work_PackageModel"
}
}
},
"_links": {
"type": "object",
"required": [
"self",
"container",
"creator",
"originOpen",
"staticOriginOpen",
"originOpenLocation",
"staticOriginOpenLocation"
],
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "This file link.\n\n**Resource**: FileLink"
}
]
},
"storage": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The storage resource of the linked file.\n\n**Resource**: Storage"
}
]
},
"container": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The container the origin file is linked to.\n\nCan be one of the following **Resources**: \n\n- WorkPackage"
}
]
},
"creator": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The creator of the file link.\n\n**Resource**: User"
}
]
},
"delete": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The uri to delete the file link.\n\n**Resource**: N/A"
}
]
},
"originOpen": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The uri to open the origin file on the origin itself.\n\n**Resource**: N/A"
}
]
},
"staticOriginOpen": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "A static uri to open the origin file on the storage. Responds with a redirect.\n\n**Resource**: N/A"
}
]
},
"originOpenLocation": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The uri to open the location of origin file on the origin itself.\n\n**Resource**: N/A"
}
]
},
"staticOriginOpenLocation": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "A static uri to open the location of the origin file on the storage. Responds with a redirect.\n\n**Resource**: N/A"
}
]
}
}
}
},
"example": {
"id": 1337,
"_type": "FileLink",
"createdAt": "2021-12-20T13:37:00.211Z",
"updatedAt": "2021-12-20T13:37:00.211Z",
"originData": {
"id": 5503,
"name": "logo.png",
"mimeType": "image/png",
"size": 16042,
"createdAt": "2021-12-19T09:42:10.170Z",
"lastModifiedAt": "2021-12-20T14:00:13.987Z",
"createdByName": "Luke Skywalker",
"lastModifiedByName": "Anakin Skywalker"
},
"_embedded": {
"storage": {
"id": 1337,
"_type": "Storage",
"name": "It's no moon",
"createdAt": "2021-12-20T13:37:00.211Z",
"updatedAt": "2021-12-20T13:37:00.211Z",
"_links": {
"self": {
"href": "/api/v3/storages/1337",
"title": "It's no moon"
},
"type": {
"href": "urn:openproject-org:api:v3:storages:nextcloud",
"title": "Nextcloud"
},
"origin": {
"href": "https://nextcloud.deathstar.rocks/"
}
}
},
"container": {
"_hint": "Work package resource shortened for brevity",
"_type": "WorkPackage",
"_links": {
"self": {
"href": "/api/v3/work_packages/1528",
"title": "Develop API"
},
"schema": {
"href": "/api/v3/work_packages/schemas/11-2"
}
},
"id": 1528,
"subject": "Develop API",
"description": {
"format": "markdown",
"raw": "Develop super cool OpenProject API.",
"html": "<p>Develop super cool OpenProject API.</p>"
},
"scheduleManually": false,
"startDate": null,
"dueDate": null,
"createdAt": "2014-08-29T12:40:53Z",
"updatedAt": "2014-08-29T12:44:41Z"
}
},
"_links": {
"self": {
"href": "/api/v3/work_package/17/file_links/1337"
},
"storage": {
"href": "/api/v3/storage/42",
"title": "It's no moon"
},
"container": {
"href": "/api/v3/work_package/17",
"title": "Develop API"
},
"creator": {
"href": "/api/v3/users/33",
"title": "Obi-Wan Kenobi"
},
"delete": {
"href": "/api/v3/work_package/17/file_links/1337"
},
"originOpen": {
"href": "https://nextcloud.deathstar.rocks/index.php/f/5503?openfile=1"
},
"staticOriginOpen": {
"href": "/api/v3/work_package/17/file_links/1337/open"
},
"originOpenLocation": {
"href": "https://nextcloud.deathstar.rocks/index.php/f/5503?openfile=0"
},
"staticOriginOpenLocation": {
"href": "/api/v3/work_package/17/file_links/1337/open?location=true"
}
}
}
}
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, view file links
Content-Type: application/hal+json
{
"_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."
}
}
}
Removes a file link.
delete /api/v3/file_links/{id}
Removes a file link on a work package.
The request contains only the file link identifier as a path parameter. No request body is needed.
id
integer
required path
File link id
Example:
42
200
OK
403
Returned if the client does not have sufficient permissions.
Required permission: manage file links
Note that you will only receive this error, if you are at least allowed to see the corresponding work package.
Content-Type: application/hal+json
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse
{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
404
Returned if the work package or the file link does not exist or the client does not have sufficient permissions to see it.
Required permission: view work package, view file links
Content-Type: application/hal+json
{
"_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."
}
}
}
Creates an opening uri of the linked file.
get /api/v3/file_links/{id}/open
Creates a uri to open the origin file linked by the given file link. This uri depends on the storage type and always is located on the origin storage itself.
id
integer
required path
File link id
Example:
42
location
boolean
optional query
Boolean flag indicating, if the file should be opened directly or rather the directory location.
Example:
true
303
Returned if the request was successful. In the Location header is the uri where the client can open the origin file on the storage.
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, view file links
Content-Type: application/hal+json
{
"_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."
}
}
}
Gets a file link.
Gets a storage resource.
id
integer
required path
Storage id
Example:
1337
200
OK
Content-Type: application/hal+json
StorageModel
{
"type": "object",
"required": [
"id",
"_type",
"name",
"storageType"
],
"properties": {
"id": {
"type": "integer",
"description": "Storage id"
},
"_type": {
"type": "string",
"enum": [
"Storage"
]
},
"name": {
"type": "string",
"description": "Storage name"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Time of creation"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Time of the most recent change to the storage"
},
"_links": {
"type": "object",
"required": [
"self",
"type",
"href"
],
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "This storage resource. Contains the user defined storage name as title.\n\n**Resource**: Storage"
}
]
},
"type": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The urn of the storage type. Currently only nextcloud storages are supported.\n\n**Resource**: N/A"
}
]
},
"origin": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Web uri of the storage instance\n\n**Resource**: N/A"
}
]
}
}
}
},
"example": {
"id": 1337,
"_type": "Storage",
"name": "It's no moon",
"createdAt": "2021-12-20T13:37:00.211Z",
"updatedAt": "2021-12-20T13:37:00.211Z",
"_links": {
"self": {
"href": "/api/v3/storages/1337",
"title": "It's no moon"
},
"type": {
"href": "urn:openproject-org:api:v3:storages:nextcloud",
"title": "Nextcloud"
},
"origin": {
"href": "https://nextcloud.deathstar.rocks/"
}
}
}
}
404
Returned if the storage does not exist or the client does not have sufficient permissions to see it.
Required permission: view file links
Content-Type: application/hal+json
{
"_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."
}
}
}
Gets all file links of a work package
get /api/v3/work_packages/{id}/file_links
Gets all file links of a work package.
id
integer
required path
Work package id
Example:
1337
200
OK
Content-Type: application/hal+json
FileLinkCollectionReadModel
{
"allOf": [
{
"$ref": "#/components/schemas/CollectionModel"
},
{
"type": "object",
"required": [
"_links",
"_embedded"
],
"properties": {
"_links": {
"type": "object",
"required": [
"self"
],
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "This file links collection\n\n**Resource**: FileLinkCollectionReadModel"
}
]
}
}
},
"_embedded": {
"type": "object",
"required": [
"elements"
],
"properties": {
"elements": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FileLinkReadModel"
}
}
}
}
}
}
],
"example": {
"_type": "Collection",
"total": 2,
"count": 2,
"_links": {
"self": {
"href": "/api/v3/work_packages/42/file_links"
}
},
"_embedded": {
"elements": [
{
"id": 1337,
"_type": "FileLink",
"createdAt": "2021-12-20T13:37:00.211Z",
"updatedAt": "2021-12-20T13:37:00.211Z",
"originData": {
"id": 5503,
"name": "logo.png",
"mimeType": "image/png",
"size": 16042,
"createdAt": "2021-12-19T09:42:10.170Z",
"lastModifiedAt": "2021-12-20T14:00:13.987Z",
"createdByName": "Luke Skywalker",
"lastModifiedByName": "Anakin Skywalker"
},
"_links": {
"self": {
"href": "/api/v3/work_package/17/file_links/1337",
"title": "file link"
},
"storage": {
"href": "/api/v3/storage/42",
"title": "storage"
},
"container": {
"href": "/api/v3/work_package/17",
"title": "work package"
},
"creator": {
"href": "/api/v3/users/33",
"title": "Obi-Wan Kenobi"
},
"delete": {
"href": "/api/v3/work_package/17/file_links/1337",
"method": "delete"
},
"originOpen": {
"href": "https://nextcloud.deathstar.rocks/index.php/f?fileid=5503"
},
"staticOriginOpen": {
"href": "/api/v3/work_package/17/file_links/1337/open"
}
}
},
{
"_hint": "File Link resource shortened for brevity",
"id": 1338
}
]
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: view file links
Note that you will only receive this error, if you are at least allowed to see the corresponding work package.
Content-Type: application/hal+json
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse
{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
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
Content-Type: application/hal+json
{
"_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."
}
}
}
Creates file links.
post /api/v3/work_packages/{id}/file_links
Creates file links on a work package.
The request is interpreted as a bulk insert, where every element of the collection is validated separately. Each element contains the origin meta data and a link to the storage, the file link is about to point to. The storage link can be provided as a resource link with id or as the host url.
The file’s id and name are considered mandatory information. The rest of the origin meta data SHOULD be provided by the client. The mimeType SHOULD be a standard mime type. An empty mime type will be handled as unknown. To link a folder, the custom mime type inode/directory MUST be used.
Up to 20 file links can be submitted at once.
If any element data is invalid, no file links will be created.
If a file link with matching origin id, work package, and storage already exists, then it will not create an additional file link or update the meta data. Instead the information from the existing file link will be returned.
id
integer
required path
Work package id
Example:
1337
201
Created
Content-Type: application/hal+json
FileLinkCollectionReadModel
{
"allOf": [
{
"$ref": "#/components/schemas/CollectionModel"
},
{
"type": "object",
"required": [
"_links",
"_embedded"
],
"properties": {
"_links": {
"type": "object",
"required": [
"self"
],
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "This file links collection\n\n**Resource**: FileLinkCollectionReadModel"
}
]
}
}
},
"_embedded": {
"type": "object",
"required": [
"elements"
],
"properties": {
"elements": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FileLinkReadModel"
}
}
}
}
}
}
],
"example": {
"_type": "Collection",
"total": 2,
"count": 2,
"_links": {
"self": {
"href": "/api/v3/work_packages/42/file_links"
}
},
"_embedded": {
"elements": [
{
"id": 1337,
"_type": "FileLink",
"createdAt": "2021-12-20T13:37:00.211Z",
"updatedAt": "2021-12-20T13:37:00.211Z",
"originData": {
"id": 5503,
"name": "logo.png",
"mimeType": "image/png",
"size": 16042,
"createdAt": "2021-12-19T09:42:10.170Z",
"lastModifiedAt": "2021-12-20T14:00:13.987Z",
"createdByName": "Luke Skywalker",
"lastModifiedByName": "Anakin Skywalker"
},
"_links": {
"self": {
"href": "/api/v3/work_package/17/file_links/1337",
"title": "file link"
},
"storage": {
"href": "/api/v3/storage/42",
"title": "storage"
},
"container": {
"href": "/api/v3/work_package/17",
"title": "work package"
},
"creator": {
"href": "/api/v3/users/33",
"title": "Obi-Wan Kenobi"
},
"delete": {
"href": "/api/v3/work_package/17/file_links/1337",
"method": "delete"
},
"originOpen": {
"href": "https://nextcloud.deathstar.rocks/index.php/f?fileid=5503"
},
"staticOriginOpen": {
"href": "/api/v3/work_package/17/file_links/1337/open"
}
}
},
{
"_hint": "File Link resource shortened for brevity",
"id": 1338
}
]
}
}
}
400
Occurs when the client did not send a valid JSON object in the request body.
Content-Type: application/hal+json
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was invalid."
}
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: manage file links
Note that you will only receive this error, if you are at least allowed to see the corresponding work package.
Content-Type: application/hal+json
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse
{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
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, view file links
Content-Type: application/hal+json
{
"_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."
}
}
}
422
Occurs if the request body was correctly formatted, but some properties lead to errors in the validation process. This happens e.g. if the provided storage url is not available on the server.
Content-Type: application/hal+json
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
"message": "The request was invalid. File Link logo.png - Storage was invalid."
}
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."
}
}
}
