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
FileLinkReadModel{
"type": "object",
"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/StorageReadModel"
},
"container": {
"$ref": "#/components/schemas/WorkPackageModel"
}
}
},
"_links": {
"type": "object",
"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"
}
]
},
"status": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The urn of the user specific file link status on its storage. Can be one of:\n\n- urn:openproject-org:api:v3:file-links:permission:ViewAllowed\n- urn:openproject-org:api:v3:file-links:permission:ViewNotAllowed\n- urn:openproject-org:api:v3:file-links:NotFound\n- urn:openproject-org:api:v3:file-links:Error\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"
}
]
},
"staticOriginDownload": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "A static uri to generate a new download URL from 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",
"id": 1528,
"subject": "Develop API"
}
},
"_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"
},
"status": {
"href": "urn:openproject-org:api:v3:file-links:permission:ViewAllowed",
"title": "View allowed"
},
"originOpen": {
"href": "https://nextcloud.deathstar.rocks/index.php/f/5503?openfile=1"
},
"staticOriginOpen": {
"href": "/api/v3/file_links/1337/open"
},
"originOpenLocation": {
"href": "https://nextcloud.deathstar.rocks/index.php/f/5503?openfile=0"
},
"staticOriginOpenLocation": {
"href": "/api/v3/file_links/1337/open?location=true"
},
"staticOriginDownload": {
"href": "/api/v3/file_links/1337/download"
}
}
}
}
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
{
"_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.
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.
{
"_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
{
"_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 a download uri of the linked file.
Creates a uri to download the origin file linked by the given file link. This uri depends on the storage type and is always located on the origin storage itself.
id
integer
required path
File link id
Example:42
303
Returned if the request was successful. In the Location header is the uri where the client can download the origin file from 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
{
"_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.
Creates a uri to open the origin file linked by the given file link. This uri depends on the storage type and is always 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
{
"_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."
}
}
}
Get storages
Returns a collection of storages.
No parameters
200
OK
{
"_type": "Collection",
"count": 2,
"total": 2,
"offset": 1,
"pageSize": 20,
"_embedded": {
"elements": [
{
"id": 1337,
"_type": "Storage",
"name": "It's no moon",
"hasApplicationPassword": true,
"configured": true,
"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/"
},
"open": {
"href": "https://nextcloud.deathstar.rocks/apps/files"
},
"authorizationState": {
"href": "urn:openproject-org:api:v3:storages:authorization:FailedAuthorization",
"title": "Failed Authorization"
},
"authorize": {
"href": "https://nextcloud.deathstar.rocks/authorize/",
"title": "Authorize"
},
"projectStorages": {
"href": "/api/v3/project_storages?filters=[{\"storageId\":{\"operator\":\"=\",\"values\":[\"1337\"]}}]"
},
"oauthApplication": {
"href": "/api/v3/oauth_application/42",
"title": "It's no moon (Nextcloud)"
},
"oauthClientCredentials": {
"href": "/api/v3/oauth_client_credentials/42"
}
}
},
{
"id": 1338,
"_type": "Storage",
"name": "EmpireSharepoint",
"tenantId": "e36f1dbc-fdae-427e-b61b-0d96ddfb81a4",
"driveId": "b!FeOZEMfQx0eGQKqVBLcP__BG8mq-4-9FuRqOyk3MXY8Qconfm2i6SKEoCmuGYqQK",
"createdAt": "2021-12-20T13:37:00.211Z",
"updatedAt": "2021-12-20T13:37:00.211Z",
"configured": true,
"_links": {
"self": {
"href": "/api/v3/storages/1338",
"title": "EmpireSharepoint"
},
"type": {
"href": "urn:openproject-org:api:v3:storages:one-drive",
"title": "OneDrive"
},
"open": {
"href": "https://empire.sharepoint.com/sites/Documents"
},
"authorizationState": {
"href": "urn:openproject-org:api:v3:storages:authorization:Connected",
"title": "Connected"
},
"projectStorages": {
"href": "/api/v3/project_storages?filters=[{\"storageId\":{\"operator\":\"=\",\"values\":[\"1338\"]}}]"
},
"oauthClientCredentials": {
"href": "/api/v3/oauth_client_credentials/44"
}
}
}
]
}
}
StorageCollectionModel{
"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 storage collection\n\n**Resource**: StorageCollectionReadModel"
}
]
}
}
},
"_embedded": {
"type": "object",
"required": [
"elements"
],
"properties": {
"elements": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StorageReadModel"
}
}
}
}
}
}
]
}
400
Returned if the client sends invalid request parameters e.g. filters
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
"message": "Filters Invalid filter 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."
}
}
}
Creates a storage.
Creates a storage resource. When creating a storage, a confidential OAuth 2 provider application is created automatically. The oauth client id and secret of the created OAuth application are returned in the response.
IMPORTANT: This is the only time, the oauth client secret is visible to the consumer. After that, the secret is hidden.
To update the storage with OAuth client credentials, which enable the storage resource to behave as an OAuth 2 client against an external OAuth 2 provider application, another request must be made to create those, see POST /api/v3/storages/{id}/oauth_client_credentials.
No parameters
{
"name": "Coruscant",
"applicationPassword": "qJ_VLNReW@sd-Edz2hyC",
"_links": {
"origin": {
"href": "https://nextcloud.deathstar.rocks"
},
"type": {
"href": "urn:openproject-org:api:v3:storages:Nextcloud"
}
}
}
{
"name": {
"type": "string",
"description": "Storage name, if not provided, falls back to a default."
},
"storageAudience": {
"type": "string",
"description": "The audience that the storage expects in tokens for requests to it,\nusually the storage's client ID at the identity provider.\n\nThis is only required for authentication through single-sign-on and so far\nonly supported for provider type Nextcloud."
},
"applicationPassword": {
"type": [
"string",
"null"
],
"description": "The application password to use for the Nextcloud storage. Ignored if the provider type is not Nextcloud.\n\nIf a string is provided, the password is set and automatic management is enabled for the storage.\nIf null is provided, the password is unset and automatic management is disabled for the storage."
},
"_links": {
"type": "object",
"required": [
"origin",
"type"
],
"properties": {
"origin": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The storage's host URL.\n\n**Resource**: N/A"
}
]
},
"type": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The urn of the storage type. Currently Nextcloud and OneDrive storages are supported.\n\n- urn:openproject-org:api:v3:storages:Nextcloud\n- urn:openproject-org:api:v3:storages:OneDrive\n\n**Resource**: N/A"
}
]
},
"authenticationMethod": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The urn of the authentication method. Currently only Nextcloud storages support this setting.\n\n- urn:openproject-org:api:v3:storages:authenticationMethod:TwoWayOAuth2 (default)\n- urn:openproject-org:api:v3:storages:authenticationMethod:OAuth2SSO\n\n**Resource**: N/A"
}
]
}
}
}
}
201
Created
StorageReadModel{
"type": "object",
"required": [
"id",
"_type",
"name",
"_links"
],
"properties": {
"id": {
"type": "integer",
"description": "Storage id"
},
"_type": {
"type": "string",
"enum": [
"Storage"
]
},
"name": {
"type": "string",
"description": "Storage name"
},
"storageAudience": {
"type": "string",
"description": "The audience that the storage expects in tokens for requests to it,\nusually the storage's client ID at the identity provider.\n\nThis is only required for authentication through single-sign-on and so far\nonly supported for provider type Nextcloud."
},
"tenantId": {
"type": "string",
"description": "The tenant id of a file storage of type OneDrive/SharePoint.\n\nIgnored if the provider type is not OneDrive/SharePoint."
},
"driveId": {
"type": "string",
"description": "The drive id of a file storage of type OneDrive/SharePoint.\n\nIgnored if the provider type is not OneDrive/SharePoint."
},
"hasApplicationPassword": {
"type": "boolean",
"description": "Whether the storage has the application password to use for the Nextcloud storage.\n\nIgnored if the provider type is not Nextcloud."
},
"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"
},
"configured": {
"type": "boolean",
"description": "Indication, if the storage is fully configured"
},
"_embedded": {
"type": "object",
"properties": {
"oauthApplication": {
"$ref": "#/components/schemas/OAuthApplicationReadModel"
},
"oauthClientCredentials": {
"$ref": "#/components/schemas/OAuthClientCredentialsReadModel"
}
}
},
"_links": {
"type": "object",
"required": [
"self",
"type",
"open",
"authorizationState"
],
"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 Nextcloud and OneDrive storages are supported.\n\n- urn:openproject-org:api:v3:storages:Nextcloud\n- urn:openproject-org:api:v3:storages:OneDrive\n\n**Resource**: N/A"
}
]
},
"authenticationMethod": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The urn of the authentication method. Currently only Nextcloud storages support this setting.\n\n- urn:openproject-org:api:v3:storages:authenticationMethod:TwoWayOAuth2 (default)\n- urn:openproject-org:api:v3:storages:authenticationMethod:OAuth2SSO\n\n**Resource**: N/A"
}
]
},
"origin": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Web URI of the storage instance. This link is ignored, if the storage is hosted in a cloud and has no own\nURL, like file storages of type OneDrive/SharePoint.\n\n**Resource**: N/A"
}
]
},
"open": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "URI of the file storage location, from where the user usually starts browsing files.\n\n**Resource**: N/A"
}
]
},
"authorizationState": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The urn of the storage connection state. Can be one of:\n\n- urn:openproject-org:api:v3:storages:authorization:Connected\n- urn:openproject-org:api:v3:storages:authorization:FailedAuthorization\n- urn:openproject-org:api:v3:storages:authorization:Error\n\n**Resource**: N/A"
}
]
},
"authorize": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The link to the starting point of the authorization cycle for a configured storage provider.\n\n# Conditions\n\n`authorizationState` is:\n\n- urn:openproject-org:api:v3:storages:authorization:FailedAuthorization\n\n**Resource**: N/A"
}
]
},
"oauthApplication": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The OAuth 2 provider application linked to the storage.\n\n# Conditions\n\n- User has role `admin`\n\n**Resource**: OAuthApplication"
}
]
},
"oauthClientCredentials": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The OAuth 2 credentials resource linked to the storage.\n\n# Conditions\n\n- User has role `admin`\n\n**Resource**: OAuthClientCredentials"
}
]
}
}
}
}
}
400
Occurs when the client did not send a valid JSON object in the request body.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
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: Depends on the page the grid is defined for.
{
"_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."
}
}
}
406
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:
- a constraint for a property was violated (
PropertyConstraintViolation)
Get a storage
Gets a storage resource. As a side effect, a live connection to the storages origin is established to retrieve connection state data.
id
integer
required path
Storage id
Example:1337
200
OK
{
"_type": "Storage",
"id": 1337,
"name": "It's no moon",
"hasApplicationPassword": true,
"createdAt": "2021-12-20T13:37:00.211Z",
"updatedAt": "2021-12-20T13:37:00.211Z",
"configured": true,
"_embedded": {
"oauthApplication": {
"id": 42,
"_type": "OAuthApplication",
"name": "It's no moon (Nextcloud)",
"clientId": "O5h6WObhMg1Z8IcLHRE3_LMh4jJYmmca2V6OTFSv8DA",
"confidential": true,
"createdAt": "2022-12-07T12:56:42.626Z",
"updatedAt": "2022-12-07T12:56:42.626Z",
"scopes": [
"api_v3"
],
"_links": {
"self": {
"href": "/api/v3/oauth_applications/42"
},
"owner": {
"href": "/api/v3/users/13",
"title": "Darth Vader"
},
"integration": {
"href": "/api/v3/storages/1337",
"title": "It's no moon"
},
"redirectUri": [
{
"href": "https://nextcloud.deathstar.rocks/index.php/apps/integration_openproject/oauth-redirect"
}
]
}
},
"oauthClientCredentials": {
"_type": "OAuthClientCredentials",
"id": 42,
"clientId": "fGEFWxIpROrpci25TW6qWCZozDFEAKSkonMBkrf3LYvBXRljBbLajBf2vD2fjePm",
"confidential": true,
"createdAt": "2023-12-08T09:49:24.397Z",
"updatedAt": "2023-12-08T09:49:24.397Z",
"_links": {
"self": {
"href": "/api/v3/oauth_client_credentials/42"
},
"integration": {
"href": "/api/v3/storages/1337",
"title": "It's no moon"
}
}
}
},
"_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/"
},
"prepareUpload": [
{
"href": "/api/v3/storages/1337/files/prepare_upload",
"method": "post",
"title": "Upload file",
"payload": {
"projectId": 21,
"fileName": "{fileName}",
"parent": "{parent}"
},
"templated": true
},
{
"href": "/api/v3/storages/95/files/prepare_upload",
"method": "post",
"title": "Upload file",
"payload": {
"projectId": 11,
"fileName": "{fileName}",
"parent": "{parent}"
},
"templated": true
}
],
"open": {
"href": "/api/v3/storages/1337/open"
},
"authorizationState": {
"href": "urn:openproject-org:api:v3:storages:authorization:Connected",
"title": "Connected"
},
"projectStorages": {
"href": "/api/v3/project_storages?filters=[{\"storageId\":{\"operator\":\"=\",\"values\":[\"1337\"]}}]"
},
"oauthApplication": {
"href": "/api/v3/oauth_application/42",
"title": "It's no moon (Nextcloud)"
},
"oauthClientCredentials": {
"href": "/api/v3/oauth_client_credentials/42"
}
}
}
{
"_type": "Storage",
"id": 1337,
"name": "My New DeathStar",
"hasApplicationPassword": false,
"createdAt": "2024-05-21T09:11:53.880Z",
"updatedAt": "2024-05-21T09:11:53.880Z",
"configured": false,
"_embedded": {
"oauthApplication": {
"id": 42,
"_type": "OAuthApplication",
"name": "My New DeathStar (Nextcloud)",
"clientId": "gNQ-gi3VX59ruoft5B9aRmukEYbZOhKIsxXE9iT1tcQ",
"confidential": true,
"clientSecret": "79hIlb1Ezj5kPx8LgE6LI9L1-mb8g7jX1-u_a08RJlI",
"createdAt": "2024-05-21T09:11:53.908Z",
"updatedAt": "2024-05-21T09:11:53.908Z",
"scopes": [
"api_v3"
],
"_links": {
"self": {
"href": "/api/v3/oauth_applications/42"
},
"owner": {
"href": "/api/v3/users/13",
"title": "Darth Vader"
},
"integration": {
"href": "/api/v3/storages/1337",
"title": "My New DeathStar"
},
"redirectUri": [
{
"href": "https://nextcloud.deathstar.rocks/index.php/apps/integration_openproject/oauth-redirect"
}
]
}
}
},
"_links": {
"self": {
"href": "/api/v3/storages/1337",
"title": "My New DeathStar"
},
"type": {
"href": "urn:openproject-org:api:v3:storages:Nextcloud",
"title": "Nextcloud"
},
"origin": {
"href": "https://nextcloud.deathstar.rocks/"
},
"open": {
"href": "/api/v3/storages/1337/open"
},
"prepareUpload": [],
"authorizationState": {
"href": "urn:openproject-org:api:v3:storages:authorization:FailedAuthorization",
"title": "Authorization failed"
},
"projectStorages": {
"href": "/api/v3/project_storages?filters=[{\"storageId\":{\"operator\":\"=\",\"values\":[\"1337\"]}}]"
},
"oauthApplication": {
"href": "/api/v3/oauth_application/42",
"title": "My New DeathStar (Nextcloud)"
},
"oauthClientCredentials": {
"href": null
}
}
}
{
"_type": "Storage",
"id": 1337,
"name": "It's no moon",
"tenantId": "e36f1dbc-fdae-427e-b61b-0d96ddfb81a4",
"driveId": "b!FeOZEMfQx0eGQKqVBLcP__BG8mq-4-9FuRqOyk3MXY8Qconfm2i6SKEoCmuGYqQK",
"createdAt": "2021-12-20T13:37:00.211Z",
"updatedAt": "2021-12-20T13:37:00.211Z",
"configured": true,
"_embedded": {
"oauthClientCredentials": {
"_type": "OAuthClientCredentials",
"id": 42,
"clientId": "b8a5bb54-5fb2-4e0e-9427-9d24dbac32ff",
"confidential": true,
"createdAt": "2023-12-08T09:49:24.397Z",
"updatedAt": "2023-12-08T09:49:24.397Z",
"_links": {
"self": {
"href": "/api/v3/oauth_client_credentials/42"
},
"integration": {
"href": "/api/v3/storages/1337",
"title": "It's no moon"
}
}
}
},
"_links": {
"self": {
"href": "/api/v3/storages/1337",
"title": "It's no moon"
},
"type": {
"href": "urn:openproject-org:api:v3:storages:OneDrive",
"title": "OneDrive/SharePoint"
},
"prepareUpload": [
{
"href": "/api/v3/storages/1337/files/prepare_upload",
"method": "post",
"title": "Upload file",
"payload": {
"projectId": 33,
"fileName": "{fileName}",
"parent": "{parent}"
},
"templated": true
}
],
"open": {
"href": "/api/v3/storages/1337/open"
},
"authorizationState": {
"href": "urn:openproject-org:api:v3:storages:authorization:Connected",
"title": "Connected"
},
"projectStorages": {
"href": "/api/v3/project_storages?filters=[{\"storageId\":{\"operator\":\"=\",\"values\":[\"1337\"]}}]"
},
"oauthClientCredentials": {
"href": "/api/v3/oauth_client_credentials/42"
}
}
}
{
"_type": "Storage",
"id": 1337,
"name": "It's no moon",
"tenantId": "e36f1dbc-fdae-427e-b61b-0d96ddfb81a4",
"driveId": null,
"createdAt": "2021-12-20T13:37:00.211Z",
"updatedAt": "2021-12-20T13:37:00.211Z",
"configured": false,
"_links": {
"self": {
"href": "/api/v3/storages/1337",
"title": "It's no moon"
},
"type": {
"href": "urn:openproject-org:api:v3:storages:OneDrive",
"title": "OneDrive/SharePoint"
},
"prepareUpload": [],
"open": {
"href": "/api/v3/storages/1337/open"
},
"authorizationState": {
"href": "urn:openproject-org:api:v3:storages:authorization:FailedAuthorization",
"title": "Authorization failed"
},
"projectStorages": {
"href": "/api/v3/project_storages?filters=[{\"storageId\":{\"operator\":\"=\",\"values\":[\"1337\"]}}]"
},
"oauthClientCredentials": {
"href": "/api/v3/oauth_client_credentials/42"
}
}
}
{
"_type": "Storage",
"id": 1337,
"name": "It's no moon",
"hasApplicationPassword": false,
"createdAt": "2021-12-20T13:37:00.211Z",
"updatedAt": "2021-12-20T13:37:00.211Z",
"configured": true,
"_embedded": {
"oauthApplication": {
"id": 42,
"_type": "OAuthApplication",
"name": "It's no moon (Nextcloud)",
"clientId": "O5h6WObhMg1Z8IcLHRE3_LMh4jJYmmca2V6OTFSv8DA",
"confidential": true,
"createdAt": "2022-12-07T12:56:42.626Z",
"updatedAt": "2022-12-07T12:56:42.626Z",
"scopes": [
"api_v3"
],
"_links": {
"self": {
"href": "/api/v3/oauth_applications/42"
},
"owner": {
"href": "/api/v3/users/13",
"title": "Darth Vader"
},
"integration": {
"href": "/api/v3/storages/1337",
"title": "It's no moon"
},
"redirectUri": [
{
"href": "https://nextcloud.deathstar.rocks/index.php/apps/integration_openproject/oauth-redirect"
}
]
}
},
"oauthClientCredentials": {
"_type": "OAuthClientCredentials",
"id": 42,
"clientId": "fGEFWxIpROrpci25TW6qWCZozDFEAKSkonMBkrf3LYvBXRljBbLajBf2vD2fjePm",
"confidential": true,
"createdAt": "2023-12-08T09:49:24.397Z",
"updatedAt": "2023-12-08T09:49:24.397Z",
"_links": {
"self": {
"href": "/api/v3/oauth_client_credentials/42"
},
"integration": {
"href": "/api/v3/storages/1337",
"title": "It's no moon"
}
}
}
},
"_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/"
},
"prepareUpload": [],
"open": {
"href": "/api/v3/storages/1337/open"
},
"authorizationState": {
"href": "urn:openproject-org:api:v3:storages:authorization:FailedAuthorization",
"title": "Authorization failed"
},
"authorize": {
"href": "https://nextcloud25.local/index.php/apps/oauth2/authorize?client_id=fnrIeJZqqAKGQlejuDaGhSQfCAVtoayHLACWCYcPJ0w17Pp6daPPUktkM9QaGxca&redirect_uri=https://openproject.local/oauth_clients/fnrIeJZqqAKGQlejuDaGhSQfCAVtoayHLACWCYcPJ0w17Pp6daPPUktkM9QaGxca/callback&response_type=code",
"title": "Authorize"
},
"projectStorages": {
"href": "/api/v3/project_storages?filters=[{\"storageId\":{\"operator\":\"=\",\"values\":[\"1337\"]}}]"
},
"oauthApplication": {
"href": "/api/v3/oauth_application/42",
"title": "It's no moon (Nextcloud)"
},
"oauthClientCredentials": {
"href": "/api/v3/oauth_client_credentials/42"
}
}
}
StorageReadModel{
"type": "object",
"required": [
"id",
"_type",
"name",
"_links"
],
"properties": {
"id": {
"type": "integer",
"description": "Storage id"
},
"_type": {
"type": "string",
"enum": [
"Storage"
]
},
"name": {
"type": "string",
"description": "Storage name"
},
"storageAudience": {
"type": "string",
"description": "The audience that the storage expects in tokens for requests to it,\nusually the storage's client ID at the identity provider.\n\nThis is only required for authentication through single-sign-on and so far\nonly supported for provider type Nextcloud."
},
"tenantId": {
"type": "string",
"description": "The tenant id of a file storage of type OneDrive/SharePoint.\n\nIgnored if the provider type is not OneDrive/SharePoint."
},
"driveId": {
"type": "string",
"description": "The drive id of a file storage of type OneDrive/SharePoint.\n\nIgnored if the provider type is not OneDrive/SharePoint."
},
"hasApplicationPassword": {
"type": "boolean",
"description": "Whether the storage has the application password to use for the Nextcloud storage.\n\nIgnored if the provider type is not Nextcloud."
},
"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"
},
"configured": {
"type": "boolean",
"description": "Indication, if the storage is fully configured"
},
"_embedded": {
"type": "object",
"properties": {
"oauthApplication": {
"$ref": "#/components/schemas/OAuthApplicationReadModel"
},
"oauthClientCredentials": {
"$ref": "#/components/schemas/OAuthClientCredentialsReadModel"
}
}
},
"_links": {
"type": "object",
"required": [
"self",
"type",
"open",
"authorizationState"
],
"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 Nextcloud and OneDrive storages are supported.\n\n- urn:openproject-org:api:v3:storages:Nextcloud\n- urn:openproject-org:api:v3:storages:OneDrive\n\n**Resource**: N/A"
}
]
},
"authenticationMethod": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The urn of the authentication method. Currently only Nextcloud storages support this setting.\n\n- urn:openproject-org:api:v3:storages:authenticationMethod:TwoWayOAuth2 (default)\n- urn:openproject-org:api:v3:storages:authenticationMethod:OAuth2SSO\n\n**Resource**: N/A"
}
]
},
"origin": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Web URI of the storage instance. This link is ignored, if the storage is hosted in a cloud and has no own\nURL, like file storages of type OneDrive/SharePoint.\n\n**Resource**: N/A"
}
]
},
"open": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "URI of the file storage location, from where the user usually starts browsing files.\n\n**Resource**: N/A"
}
]
},
"authorizationState": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The urn of the storage connection state. Can be one of:\n\n- urn:openproject-org:api:v3:storages:authorization:Connected\n- urn:openproject-org:api:v3:storages:authorization:FailedAuthorization\n- urn:openproject-org:api:v3:storages:authorization:Error\n\n**Resource**: N/A"
}
]
},
"authorize": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The link to the starting point of the authorization cycle for a configured storage provider.\n\n# Conditions\n\n`authorizationState` is:\n\n- urn:openproject-org:api:v3:storages:authorization:FailedAuthorization\n\n**Resource**: N/A"
}
]
},
"oauthApplication": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The OAuth 2 provider application linked to the storage.\n\n# Conditions\n\n- User has role `admin`\n\n**Resource**: OAuthApplication"
}
]
},
"oauthClientCredentials": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The OAuth 2 credentials resource linked to the storage.\n\n# Conditions\n\n- User has role `admin`\n\n**Resource**: OAuthClientCredentials"
}
]
}
}
}
}
}
404
Returned if the storage does not exist or the client does not have sufficient permissions to see it.
Required permission: view file links
{
"_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."
}
}
}
Update a storage
Updates a storage resource. Only data that is not generated by the server can be updated. This excludes the OAuth 2 application data.
id
integer
required path
Storage id
Example:1337
{
"name": "Coruscant",
"applicationPassword": "qJ_VLNReW@sd-Edz2hyC",
"_links": {
"origin": {
"href": "https://nextcloud.deathstar.rocks"
},
"type": {
"href": "urn:openproject-org:api:v3:storages:Nextcloud"
}
}
}
{
"name": {
"type": "string",
"description": "Storage name, if not provided, falls back to a default."
},
"storageAudience": {
"type": "string",
"description": "The audience that the storage expects in tokens for requests to it,\nusually the storage's client ID at the identity provider.\n\nThis is only required for authentication through single-sign-on and so far\nonly supported for provider type Nextcloud."
},
"applicationPassword": {
"type": [
"string",
"null"
],
"description": "The application password to use for the Nextcloud storage. Ignored if the provider type is not Nextcloud.\n\nIf a string is provided, the password is set and automatic management is enabled for the storage.\nIf null is provided, the password is unset and automatic management is disabled for the storage."
},
"_links": {
"type": "object",
"required": [
"origin",
"type"
],
"properties": {
"origin": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The storage's host URL.\n\n**Resource**: N/A"
}
]
},
"type": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The urn of the storage type. Currently Nextcloud and OneDrive storages are supported.\n\n- urn:openproject-org:api:v3:storages:Nextcloud\n- urn:openproject-org:api:v3:storages:OneDrive\n\n**Resource**: N/A"
}
]
},
"authenticationMethod": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The urn of the authentication method. Currently only Nextcloud storages support this setting.\n\n- urn:openproject-org:api:v3:storages:authenticationMethod:TwoWayOAuth2 (default)\n- urn:openproject-org:api:v3:storages:authenticationMethod:OAuth2SSO\n\n**Resource**: N/A"
}
]
}
}
}
}
200
OK
StorageReadModel{
"type": "object",
"required": [
"id",
"_type",
"name",
"_links"
],
"properties": {
"id": {
"type": "integer",
"description": "Storage id"
},
"_type": {
"type": "string",
"enum": [
"Storage"
]
},
"name": {
"type": "string",
"description": "Storage name"
},
"storageAudience": {
"type": "string",
"description": "The audience that the storage expects in tokens for requests to it,\nusually the storage's client ID at the identity provider.\n\nThis is only required for authentication through single-sign-on and so far\nonly supported for provider type Nextcloud."
},
"tenantId": {
"type": "string",
"description": "The tenant id of a file storage of type OneDrive/SharePoint.\n\nIgnored if the provider type is not OneDrive/SharePoint."
},
"driveId": {
"type": "string",
"description": "The drive id of a file storage of type OneDrive/SharePoint.\n\nIgnored if the provider type is not OneDrive/SharePoint."
},
"hasApplicationPassword": {
"type": "boolean",
"description": "Whether the storage has the application password to use for the Nextcloud storage.\n\nIgnored if the provider type is not Nextcloud."
},
"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"
},
"configured": {
"type": "boolean",
"description": "Indication, if the storage is fully configured"
},
"_embedded": {
"type": "object",
"properties": {
"oauthApplication": {
"$ref": "#/components/schemas/OAuthApplicationReadModel"
},
"oauthClientCredentials": {
"$ref": "#/components/schemas/OAuthClientCredentialsReadModel"
}
}
},
"_links": {
"type": "object",
"required": [
"self",
"type",
"open",
"authorizationState"
],
"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 Nextcloud and OneDrive storages are supported.\n\n- urn:openproject-org:api:v3:storages:Nextcloud\n- urn:openproject-org:api:v3:storages:OneDrive\n\n**Resource**: N/A"
}
]
},
"authenticationMethod": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The urn of the authentication method. Currently only Nextcloud storages support this setting.\n\n- urn:openproject-org:api:v3:storages:authenticationMethod:TwoWayOAuth2 (default)\n- urn:openproject-org:api:v3:storages:authenticationMethod:OAuth2SSO\n\n**Resource**: N/A"
}
]
},
"origin": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Web URI of the storage instance. This link is ignored, if the storage is hosted in a cloud and has no own\nURL, like file storages of type OneDrive/SharePoint.\n\n**Resource**: N/A"
}
]
},
"open": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "URI of the file storage location, from where the user usually starts browsing files.\n\n**Resource**: N/A"
}
]
},
"authorizationState": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The urn of the storage connection state. Can be one of:\n\n- urn:openproject-org:api:v3:storages:authorization:Connected\n- urn:openproject-org:api:v3:storages:authorization:FailedAuthorization\n- urn:openproject-org:api:v3:storages:authorization:Error\n\n**Resource**: N/A"
}
]
},
"authorize": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The link to the starting point of the authorization cycle for a configured storage provider.\n\n# Conditions\n\n`authorizationState` is:\n\n- urn:openproject-org:api:v3:storages:authorization:FailedAuthorization\n\n**Resource**: N/A"
}
]
},
"oauthApplication": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The OAuth 2 provider application linked to the storage.\n\n# Conditions\n\n- User has role `admin`\n\n**Resource**: OAuthApplication"
}
]
},
"oauthClientCredentials": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The OAuth 2 credentials resource linked to the storage.\n\n# Conditions\n\n- User has role `admin`\n\n**Resource**: OAuthClientCredentials"
}
]
}
}
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: admin
{
"_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 storage does not exist or the client does not have sufficient permissions to see it.
Required permission: view file links
{
"_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."
}
}
}
Delete a storage
Deletes a storage resource. This also deletes all related records, like the created oauth application, client, and any file links created within this storage.
id
integer
required path
Storage id
Example:1337
204
No content
403
Returned if the client does not have sufficient permissions.
Required permission: admin
{
"_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 storage does not exist or the client does not have sufficient permissions to see it.
Required permission: view file links
{
"_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 files of a storage.
Gets a collection of files from a storage.
If no parent context is given, the result is the content of the document root. With parent context given, the result contains the collections of files/directories from within the given parent file id.
If given parent context is no directory, 400 Bad Request is returned.
id
integer
required path
Storage id
Example:1337
parent
string
optional query
Parent file identification
Example:/my/data
200
OK
StorageFilesModel{
"type": "object",
"required": [
"_type",
"files",
"parent",
"ancestors",
"_links"
],
"properties": {
"_type": {
"type": "string",
"enum": [
"StorageFiles"
]
},
"files": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StorageFileModel"
},
"description": "List of files provided by the selected storage."
},
"parent": {
"allOf": [
{
"$ref": "#/components/schemas/StorageFileModel"
},
{
"description": "File of the currently selected parent directory."
}
]
},
"ancestors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StorageFileModel"
},
"description": "List of ancestors of the parent directory. Can be empty, if parent directory was root directory."
},
"_links": {
"type": "object",
"required": [
"self"
],
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Not provided\n\n**Resource**: urn:openproject-org:api:v3:storages:storage_file:no_link_provided"
}
]
}
}
}
},
"example": {
"_type": "StorageFiles",
"files": [
{
"id": 42,
"name": "readme.md",
"_type": "StorageFile",
"location": "/readme.md",
"mimeType": "text/markdown",
"size": 4096,
"createdAt": "2021-12-19T09:42:10.170Z",
"lastModifiedAt": "2021-12-20T14:00:13.987Z",
"createdByName": "Luke Skywalker",
"lastModifiedByName": "Anakin Skywalker",
"_links": {
"self": {
"href": "urn:openproject-org:api:v3:storages:storage_file:no_link_provided"
}
}
},
{
"id": 43,
"name": "readme.pdf",
"_type": "StorageFile",
"location": "/readme.pdf",
"mimeType": "application/pdf",
"size": 2048,
"createdAt": "2021-12-19T09:42:10.170Z",
"lastModifiedAt": "2021-12-20T14:00:13.987Z",
"createdByName": "Luke Skywalker",
"lastModifiedByName": "Anakin Skywalker",
"_links": {
"self": {
"href": "urn:openproject-org:api:v3:storages:storage_file:no_link_provided"
}
}
}
],
"parent": {
"id": 41,
"name": "/",
"location": "/",
"mimeType": "application/x-op-directory",
"size": 6144,
"createdAt": "2021-12-20T09:42:10.170Z",
"lastModifiedAt": "2021-12-21T14:00:13.987Z",
"createdByName": "Luke Skywalker",
"lastModifiedByName": "Anakin Skywalker",
"_links": {
"self": {
"href": "urn:openproject-org:api:v3:storages:storage_file:no_link_provided"
}
}
},
"ancestors": [],
"_links": {
"self": {
"href": "urn:openproject-org:api:v3:storages:storage_file:no_link_provided"
}
}
}
}
400
Returned if the given parent parameter value does not refer to a directory.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
"message": "The given parent is not a directory."
}
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 in either of those cases:
-
if the storage does not exist or the client does not have sufficient permissions to see it
Required permission: view file links
-
if the document root file identification does not exist on the storage
{
"_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."
}
}
}
Preparation of a direct upload of a file to the given storage.
Executes a request that prepares a link for a direct upload to the storage.
The background here is, that the client needs to make a direct request to the storage instance for file uploading, but should not get access to the credentials, which are stored in the backend. The response contains a link object, that enables the client to execute a file upload without the real credentials.
id
integer
required path
Storage id
Example:1337
{
"projectId": {
"type": "integer",
"description": "The project identifier, from where a user starts uploading a file.",
"minimum": 1
},
"fileName": {
"type": "string",
"description": "The file name."
},
"parent": {
"type": "string",
"description": "The directory to which the file is to be uploaded. For root directories, the value `/` must\nbe provided."
}
}
201
OK
StorageFileUploadLinkModel{
"type": "object",
"required": [
"_type",
"_links"
],
"properties": {
"_type": {
"type": "string",
"enum": [
"UploadLink"
]
},
"_links": {
"type": "object",
"required": [
"self",
"destination"
],
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The resource link of the upload link resource.\n\nAs the upload link is a temporal object, and cannot be retrieved again, the\nself link usually is `urn:openproject-org:api:v3:storages:upload_link:no_link_provided`.\n\n**Resource**: UploadLink"
}
]
},
"destination": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The direct upload link.\n\n**Resource**: N/A"
}
]
}
}
}
}
}
400
Returned if the given parent parameter value does not refer to a directory.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
"message": "The given parent is not a directory."
}
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
{
"_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 storage does not exist or the client does not have sufficient permissions to see it.
Required permission: view file links
{
"_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."
}
}
}
500
Returned if the outbound request to the storage has failed with any reason.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:OutboundRequest:NotFound",
"message": "An outbound request to another resource has failed with status code 404."
}
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingEnterpriseToken",
"message": "The request cannot be handled due to invalid or missing Enterprise token."
}
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."
}
}
}
Creation of a new folder
Creates a new folder under the given parent
id
integer
required path
Storage id
Example:1337
201
Created
StorageFileModel{
"allOf": [
{
"$ref": "#/components/schemas/FileLinkOriginDataModel"
},
{
"type": "object",
"required": [
"_type",
"location",
"_links"
],
"properties": {
"_type": {
"type": "string",
"enum": [
"StorageFile"
]
},
"location": {
"type": "string",
"description": "Location identification for file in storage"
},
"_links": {
"type": "object",
"required": [
"self"
],
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Not provided\n\n**Resource**: urn:openproject-org:api:v3:storages:storage_file:no_link_provided"
}
]
}
}
}
}
}
],
"example": {
"id": 42,
"name": "readme.md",
"_type": "StorageFile",
"location": "/readme.md",
"_links": {
"self": {
"href": "urn:openproject-org:api:v3:storages:storage_file:no_link_provided"
}
}
}
}
400
Returned if the request is missing a required parameter.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
"message": "The given parent is not a directory."
}
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
{
"_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 storage does not exist or the client does not have sufficient permissions to see it.
Required permission: view file links
{
"_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 oauth client credentials object for a storage.
Inserts the OAuth 2 credentials into the storage, to allow the storage to act as an OAuth 2 client. Calling this endpoint on a storage that already contains OAuth 2 client credentials will replace them.
id
integer
required path
Storage id
Example:1337
201
Created
StorageReadModel{
"type": "object",
"required": [
"id",
"_type",
"name",
"_links"
],
"properties": {
"id": {
"type": "integer",
"description": "Storage id"
},
"_type": {
"type": "string",
"enum": [
"Storage"
]
},
"name": {
"type": "string",
"description": "Storage name"
},
"storageAudience": {
"type": "string",
"description": "The audience that the storage expects in tokens for requests to it,\nusually the storage's client ID at the identity provider.\n\nThis is only required for authentication through single-sign-on and so far\nonly supported for provider type Nextcloud."
},
"tenantId": {
"type": "string",
"description": "The tenant id of a file storage of type OneDrive/SharePoint.\n\nIgnored if the provider type is not OneDrive/SharePoint."
},
"driveId": {
"type": "string",
"description": "The drive id of a file storage of type OneDrive/SharePoint.\n\nIgnored if the provider type is not OneDrive/SharePoint."
},
"hasApplicationPassword": {
"type": "boolean",
"description": "Whether the storage has the application password to use for the Nextcloud storage.\n\nIgnored if the provider type is not Nextcloud."
},
"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"
},
"configured": {
"type": "boolean",
"description": "Indication, if the storage is fully configured"
},
"_embedded": {
"type": "object",
"properties": {
"oauthApplication": {
"$ref": "#/components/schemas/OAuthApplicationReadModel"
},
"oauthClientCredentials": {
"$ref": "#/components/schemas/OAuthClientCredentialsReadModel"
}
}
},
"_links": {
"type": "object",
"required": [
"self",
"type",
"open",
"authorizationState"
],
"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 Nextcloud and OneDrive storages are supported.\n\n- urn:openproject-org:api:v3:storages:Nextcloud\n- urn:openproject-org:api:v3:storages:OneDrive\n\n**Resource**: N/A"
}
]
},
"authenticationMethod": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The urn of the authentication method. Currently only Nextcloud storages support this setting.\n\n- urn:openproject-org:api:v3:storages:authenticationMethod:TwoWayOAuth2 (default)\n- urn:openproject-org:api:v3:storages:authenticationMethod:OAuth2SSO\n\n**Resource**: N/A"
}
]
},
"origin": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Web URI of the storage instance. This link is ignored, if the storage is hosted in a cloud and has no own\nURL, like file storages of type OneDrive/SharePoint.\n\n**Resource**: N/A"
}
]
},
"open": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "URI of the file storage location, from where the user usually starts browsing files.\n\n**Resource**: N/A"
}
]
},
"authorizationState": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The urn of the storage connection state. Can be one of:\n\n- urn:openproject-org:api:v3:storages:authorization:Connected\n- urn:openproject-org:api:v3:storages:authorization:FailedAuthorization\n- urn:openproject-org:api:v3:storages:authorization:Error\n\n**Resource**: N/A"
}
]
},
"authorize": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The link to the starting point of the authorization cycle for a configured storage provider.\n\n# Conditions\n\n`authorizationState` is:\n\n- urn:openproject-org:api:v3:storages:authorization:FailedAuthorization\n\n**Resource**: N/A"
}
]
},
"oauthApplication": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The OAuth 2 provider application linked to the storage.\n\n# Conditions\n\n- User has role `admin`\n\n**Resource**: OAuthApplication"
}
]
},
"oauthClientCredentials": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The OAuth 2 credentials resource linked to the storage.\n\n# Conditions\n\n- User has role `admin`\n\n**Resource**: OAuthClientCredentials"
}
]
}
}
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: admin
{
"_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 storage does not exist or the client does not have sufficient permissions to see it.
Required permission: view file links
{
"_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
Gets all file links of a work package.
As a side effect, for every file link a request is sent to the storage’s origin to fetch live data and patch the file link’s data before returning, as well as retrieving permissions of the user on this origin file.
id
integer
required path
Work package id
Example:1337
filters
string
optional query
JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. The following filters are supported:
- storage
Example:[{"storage":{"operator":"=","values":["42"]}}]
200
OK
FileLinkCollectionReadModel{
"allOf": [
{
"$ref": "#/components/schemas/PaginatedCollectionModel"
},
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "This file links collection\n\n**Resource**: FileLinkCollectionReadModel"
}
]
}
}
},
"_embedded": {
"type": "object",
"properties": {
"elements": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FileLinkReadModel"
}
}
}
}
}
}
],
"example": {
"_type": "Collection",
"total": 2,
"count": 2,
"pageSize": 30,
"offset": 1,
"_links": {
"self": {
"href": "/api/v3/work_packages/42/file_links"
},
"jumpTo": {
"href": "/api/v3/work_packages/42/file_links?offset=%7Boffset%7D&pageSize=30",
"templated": true
},
"changeSize": {
"href": "/api/v3/work_packages/42/file_links?offset=1&pageSize=%7Bsize%7D",
"templated": true
}
},
"_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.
{
"_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
{
"_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.
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 application/x-op-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
{
"_type": "Collection",
"_embedded": {
"elements": [
{
"originData": {
"id": 5503,
"name": "logo.png",
"mimeType": "image/png",
"size": 433765,
"createdAt": "2021-12-19T09:42:10.170Z",
"lastModifiedAt": "2021-12-20T14:00:13.987Z",
"createdByName": "Luke Skywalker",
"lastModifiedByName": "Anakin Skywalker"
},
"_links": {
"storageUrl": {
"href": "https://nextcloud.deathstar.rocks/"
}
}
}
]
}
}
{
"allOf": [
{
"$ref": "#/components/schemas/CollectionModel"
},
{
"type": "object",
"required": [
"_embedded"
],
"properties": {
"_embedded": {
"type": "object",
"required": [
"elements"
],
"properties": {
"elements": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FileLinkWriteModel"
}
}
}
}
}
}
],
"example": {
"_embedded": {
"elements": [
{
"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": {
"storage": {
"href": "/api/v3/storage/42"
}
}
},
{
"_hint": "File Link resource shortened for brevity",
"id": 1338
}
]
}
}
}
201
Created
FileLinkCollectionReadModel{
"allOf": [
{
"$ref": "#/components/schemas/PaginatedCollectionModel"
},
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "This file links collection\n\n**Resource**: FileLinkCollectionReadModel"
}
]
}
}
},
"_embedded": {
"type": "object",
"properties": {
"elements": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FileLinkReadModel"
}
}
}
}
}
}
],
"example": {
"_type": "Collection",
"total": 2,
"count": 2,
"pageSize": 30,
"offset": 1,
"_links": {
"self": {
"href": "/api/v3/work_packages/42/file_links"
},
"jumpTo": {
"href": "/api/v3/work_packages/42/file_links?offset=%7Boffset%7D&pageSize=30",
"templated": true
},
"changeSize": {
"href": "/api/v3/work_packages/42/file_links?offset=1&pageSize=%7Bsize%7D",
"templated": true
}
},
"_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.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
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.
{
"_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
{
"_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
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
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.
{
"_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."
}
}
}
