Onedata API Reference

REST API references for Onezone, Oneprovider, and Onepanel.

Onezone REST API Oneprovider REST API Onepanel REST API

Register file

POST /data/register

Registers a file located on an imported storage backend. This operation is available only in spaces supported with imported storage backends with manual import mode enabled. In such setup, the files existing on the storage are not automatically visible in the space and must be registered manually by the space users - learn more.

The operation creates the necessary metadata for the file and registers its physical location on the storage in Onedata, which makes the file visible and accessible within the space. The metadata can be provided explicitly by the registering user, or an automatic detection will be performed (although not all storage backends support the required stat operation or equivalent - in such case some metadata must be provided for the operation to succeed).

The registration of the same file can be repeated, which updates the previous metadata with the new information. In most cases, the metadata is overwritten with new values, with exception of extended attributes - previous values are merged with new ones.

This operation requires:

  • space_register_file privilege

Notes for HTTP storage backends:

  • Regardless of the root server endpoint provided in the HTTP storage backend configuration, one can register any valid URL. The root endpoint is only relevant as far as custom authorization credentials are required.
  • For this kind of storage, the automatic detection of file metadata is always forced to ensure that the HTTP endpoint supports required operations: the HEAD method and Range: bytes=... header, allowing range reads. If the server lacks those, an error statOperationNotSupported is returned. If a request with autoDetectAttributes: false is made, a data validation error is returned.

Example cURL requests

Register file from a remote, read-only HTTP storage

  curl -H "X-Auth-Token: $TOKEN" -X POST "https://$PROVIDER_HOST/api/v3/oneprovider/data/register" \
  -H "Content-Type: application/json"  -d '{
    "storageId": "$STORAGE_ID",
    "spaceId": "$SPACE_ID",
    "storageFileId": "https://example-files.online-convert.com/document/txt/example.txt",
    "destinationPath": "example.txt"
  }'

Request body

application/json

Specification of a file to be registered.

PropertyType & Description
spaceId
string

Id of the space in which the file will be registered - the space must be supported by the storage backend hosting the file (storageId). The space support must have manual import mode.

storageId
string

Id of the storage hosting the file - the storage must support the target space (spaceId). The storage must be configured as an imported storage with canonical path type.

storageFileId
string

Identifier of the file on storage, relevant for given storage backend:

  • path on POSIX-compatible or canonical object storage backends, e.g. /dir/file.txt
  • URL on HTTP based storage backends, e.g. https://www.example.org/data/21/run123.tar
destinationPath
string

An absolute path in space where file should be created.

size
integer

Size of the file in bytes. If not passed, it will be acquired from storage. If storage does not support the stat operation or equivalent used for acquiring files metadata, registration will fail if this value is missing.

mode
string

User defined POSIX file permissions in octal format. If not passed, it will be acquired from storage or default "664" mode will be used.

atime
integer

User defined last access timestamp (in seconds). If not passed, it will be acquired from storage or current timestamp will be used.

mtime
integer

User defined last modification timestamp (in seconds). If not passed, it will be acquired from storage or current timestamp will be used.

ctime
integer

User defined last attributes modification timestamp (in seconds). If not passed, it will be acquired from storage or current timestamp will be used.

uid
string

User defined of the Id of the owner of this file on storage. If not passed, it will be acquired from storage or 0 will be used. This value will be mapped, using LUMA DB, to acquire Onedata user Id of the file owner.

gid
string

User defined Id of the group owner of this file on storage. If not passed, it will be acquired from storage or 0 will be used. This value will be used as display GID in getattr operation.

xattrs
object

Map with extended attributes key-value pairs which will be attached to newly created file.

json
object

Map with custom JSON metadata which will be attached to newly created file.

rdf
string

Base64 encoded RDF metadata which will be attached to newly created file.

autoDetectAttributes
boolean

Flag which determines whether additional stat operation (or equivalent) should be performed on the storage to automatically detect file attributes - they will be used if not provided explicitly in the request. The detection also ensures that the file exists - it is performed if the flag is set to true, even if all attributes are provided. If this flag is set to false, default attributes are used if not provided explicitly. The only exception is the size attribute, which is mandatory. The registration request will fail if autoDetectAttributes is set to false and size is not provided. It is possible to register a file that does not exist on storage if autoDetectAttributes is set to false. Such file will be visible in Onedata but not accessible.

Request Examples

application/json 
{
  "spaceId": "761f76677f42ad5289d6472675d5ecf2dfd57be6",
  "storageId": "2c1e539dbebf76a697e44782787585ebb0f47af1",
  "storageFileId": "https://www.example.org/data/2010/01/05/run123.tar",
  "destinationPath": "/data/2010/01/05/run123.tar",
  "mode": "664",
  "size": 1024,
  "atime": 1464958683054,
  "mtime": 1464958683051,
  "ctime": 1464958681054,
  "uid": 1935313,
  "gid": 1101841,
  "xattrs": {
    "colour": "red",
    "country": "FR",
    "checksum": "189e725f4587b679740f0f7783745056"
  },
  "json": {
    "year": 2014,
    "month": 10,
    "day": 1,
    "run": 5038219,
    "subrun": 1
  },
  "rdf": "PD94bWwgdmVyc2lvbj0iMS4wIj8+CjxyZGY6UkRGIHhtbG5zOnJkZj0iaHR0cDovL3d3dy53My5v cmcvMTk5OS8wMi8yMi1yZGYtc3ludGF4LW5zIyIKICAgICAgICAgICAgeG1sbnM6ZGM9Imh0dHA6 Ly9wdXJsLm9yZy9kYy9lbGVtZW50cy8xLjEvIgogICAgICAgICAgICB4bWxuczpleD0iaHR0cDov L2V4YW1wbGUub3JnL3N0dWZmLzEuMC8iPgoKICA8cmRmOkRlc2NyaXB0aW9uIHJkZjphYm91dD0i aHR0cDovL3d3dy53My5vcmcvVFIvcmRmLXN5bnRheC1ncmFtbWFyIgogICAgICAgICAgICAgZGM6 dGl0bGU9IlJERjEuMSBYTUwgU3ludGF4Ij4KICAgIDxleDplZGl0b3I+CiAgICAgIDxyZGY6RGVz Y3JpcHRpb24gZXg6ZnVsbE5hbWU9IkRhdmUgQmVja2V0dCI+CiAgICAgICAgPGV4OmhvbWVQYWdl IHJkZjpyZXNvdXJjZT0iaHR0cDovL3B1cmwub3JnL25ldC9kYWpvYmUvIiAvPgogICAgICA8L3Jk ZjpEZXNjcmlwdGlvbj4KICAgIDwvZXg6ZWRpdG9yPgogIDwvcmRmOkRlc2NyaXB0aW9uPgoKPC9y ZGY6UkRGPgo=\n",
  "autoDetectAttributes": true
}

Responses

application/json
201

The file has been registered in the Onedata file-system and the result is its Id. Also URI of the new file in form https://$PROVIDER_HOST/api/v3/oneprovider/data/{Id} is returned in the response Location header.

PropertyType & Description
fileId
string

New file Id.

400

Invalid request.

PropertyType & Description
error
object (ErrorJson)

Object describing an error.

id required
string

String identifying the error type. Does not change between error instances.

description required
string

Human readable error description. May contain information specific to given error instance.

details
object

Details about the error instance. The object schema is specific to each error type.

ctx required
object (ErrorJsonCtx)

Technical information about error.

timestamp required
integer

Timestamp in milliseconds.

serviceReleaseVersion required
string

Release version of a product, for example "25.0".

serviceId required
string

Identifier of a service instance — either Oneprovider Id or "onezone".

serviceDomain required
string

Domain of the service.

serviceBuildVersion required
string

Build version of the service.

service required
string

Short name of service.

Enum:
ozwopwozpopp
onedataErrorsRevision required
string

Revision of onedata-errors repo, where the error is defined.

module required
string

Module where the error occurred.

line required
integer

Line number in the module where the error occurred.

Example

application/json
{
  "error": {
    "id": "example",
    "description": "This is an example error.",
    "ctx": {
      "timestamp": 1750762637248,
      "serviceReleaseVersion": "25.0",
      "serviceId": "a7ee2722915b8bf7fb064eb65087cc61ch9357",
      "serviceDomain": "dev-oneprovider-krakow.default.svc.cluster.local",
      "serviceBuildVersion": "231-g8d26f953c3",
      "service": "opw",
      "onedataErrorsRevision": "ca3af8cb",
      "module": "metadata_req",
      "line": 45
    }
  }
}
403

Forbidden request.

PropertyType & Description
error
object (ErrorJson)

Object describing an error.

id required
string

String identifying the error type. Does not change between error instances.

description required
string

Human readable error description. May contain information specific to given error instance.

details
object

Details about the error instance. The object schema is specific to each error type.

ctx required
object (ErrorJsonCtx)

Technical information about error.

timestamp required
integer

Timestamp in milliseconds.

serviceReleaseVersion required
string

Release version of a product, for example "25.0".

serviceId required
string

Identifier of a service instance — either Oneprovider Id or "onezone".

serviceDomain required
string

Domain of the service.

serviceBuildVersion required
string

Build version of the service.

service required
string

Short name of service.

Enum:
ozwopwozpopp
onedataErrorsRevision required
string

Revision of onedata-errors repo, where the error is defined.

module required
string

Module where the error occurred.

line required
integer

Line number in the module where the error occurred.

Example

application/json
{
  "error": {
    "id": "example",
    "description": "This is an example error.",
    "ctx": {
      "timestamp": 1750762637248,
      "serviceReleaseVersion": "25.0",
      "serviceId": "a7ee2722915b8bf7fb064eb65087cc61ch9357",
      "serviceDomain": "dev-oneprovider-krakow.default.svc.cluster.local",
      "serviceBuildVersion": "231-g8d26f953c3",
      "service": "opw",
      "onedataErrorsRevision": "ca3af8cb",
      "module": "metadata_req",
      "line": 45
    }
  }
}
404

At least one of the required resources (space, storage backend or file on the storage) does not exist.

PropertyType & Description
error
object (ErrorJson)

Object describing an error.

id required
string

String identifying the error type. Does not change between error instances.

description required
string

Human readable error description. May contain information specific to given error instance.

details
object

Details about the error instance. The object schema is specific to each error type.

ctx required
object (ErrorJsonCtx)

Technical information about error.

timestamp required
integer

Timestamp in milliseconds.

serviceReleaseVersion required
string

Release version of a product, for example "25.0".

serviceId required
string

Identifier of a service instance — either Oneprovider Id or "onezone".

serviceDomain required
string

Domain of the service.

serviceBuildVersion required
string

Build version of the service.

service required
string

Short name of service.

Enum:
ozwopwozpopp
onedataErrorsRevision required
string

Revision of onedata-errors repo, where the error is defined.

module required
string

Module where the error occurred.

line required
integer

Line number in the module where the error occurred.

Example

application/json
{
  "error": {
    "id": "example",
    "description": "This is an example error.",
    "ctx": {
      "timestamp": 1750762637248,
      "serviceReleaseVersion": "25.0",
      "serviceId": "a7ee2722915b8bf7fb064eb65087cc61ch9357",
      "serviceDomain": "dev-oneprovider-krakow.default.svc.cluster.local",
      "serviceBuildVersion": "231-g8d26f953c3",
      "service": "opw",
      "onedataErrorsRevision": "ca3af8cb",
      "module": "metadata_req",
      "line": 45
    }
  }
}
500

Internal server error.

PropertyType & Description
error
object (ErrorJson)

Object describing an error.

id required
string

String identifying the error type. Does not change between error instances.

description required
string

Human readable error description. May contain information specific to given error instance.

details
object

Details about the error instance. The object schema is specific to each error type.

ctx required
object (ErrorJsonCtx)

Technical information about error.

timestamp required
integer

Timestamp in milliseconds.

serviceReleaseVersion required
string

Release version of a product, for example "25.0".

serviceId required
string

Identifier of a service instance — either Oneprovider Id or "onezone".

serviceDomain required
string

Domain of the service.

serviceBuildVersion required
string

Build version of the service.

service required
string

Short name of service.

Enum:
ozwopwozpopp
onedataErrorsRevision required
string

Revision of onedata-errors repo, where the error is defined.

module required
string

Module where the error occurred.

line required
integer

Line number in the module where the error occurred.

Example

application/json
{
  "error": {
    "id": "example",
    "description": "This is an example error.",
    "ctx": {
      "timestamp": 1750762637248,
      "serviceReleaseVersion": "25.0",
      "serviceId": "a7ee2722915b8bf7fb064eb65087cc61ch9357",
      "serviceDomain": "dev-oneprovider-krakow.default.svc.cluster.local",
      "serviceBuildVersion": "231-g8d26f953c3",
      "service": "opw",
      "onedataErrorsRevision": "ca3af8cb",
      "module": "metadata_req",
      "line": 45
    }
  }
}