Onedata API Reference

REST API references for Onezone, Oneprovider, and Onepanel.

Onezone REST API Oneprovider REST API Onepanel REST API

Create file at path

PUT /data/{id}/path/{path}

Creates a file at path specified in the URL, relative to the base directory given in the id parameter (see the parameter description for details). If the parent path does not exist and create_parents flag is set to true, the operation will attempt to create intermediate parent directories.

If the file already exists, the operation fails with an error.

The file type can be of:

  • REG (regular file) - in this case, the data sent in request body (if any) is saved as file content.
  • DIR (directory).
  • LNK (hard link) - requires that target_file_id pointing to a regular file is specified.
  • SYMLNK (symbolic link) - requires that target_file_path is specified. When creating symbolic link with absolute path starting from specific space it is necessary to do so by replacing /$SPACE_NAME/ in path by special prefix in the form <__onedata_space_id:$SPACE_ID>/ (where $SPACE_ID is actual space id)

Example cURL requests

Below examples will create a file called $NAME in directory dir1 that's relative to the directory specified by $SPACE_OR_PARENT_ID (effectively at /$SPACE_OR_PARENT_ID/dir1/$NAME).

Create a regular file

curl -H "X-Auth-Token: $TOKEN" \
-X PUT "https://$PROVIDER_HOST/api/v3/oneprovider/data/$SPACE_OR_PARENT_ID/path/dir1/$NAME"
-H "Content-Type: application/octet-stream" -d "@file.dat"

{
   "fileId": "094576776E667431723230677767776C6B497031394E445F6E3868677873..."
}

Create a directory

curl -H "X-Auth-Token: $TOKEN" \
-X PUT "https://$PROVIDER_HOST/api/v3/oneprovider/data/$SPACE_OR_PARENT_ID/path/dir1/$NAME?type=DIR"

{
   "fileId": "000000006CB6637368617265477569642333396432363661656463656266..."
}

Create a hard link

curl -H "X-Auth-Token: $TOKEN" \
-X PUT "https://$PROVIDER_HOST/api/v3/oneprovider/data/$SPACE_OR_PARENT_ID/path/dir1/$NAME?type=LNK&target_file_id=$TARGET_FILE_ID"

{
   "fileId": "000000184465677569642373706163655F73706163653123737061636531..."
}

Create a symbolic link

curl -H "X-Auth-Token: $TOKEN" \
-X PUT "https://$PROVIDER_HOST/api/v3/oneprovider/data/$SPACE_OR_PARENT_ID/path/dir1/$NAME?type=SYMLNK&target_file_path=$TARGET_FILE_PATH"

{
   "fileId": "00989AB98890037368617265477569642333396432363661656463656266..."
}

See also Create file in directory.

Path parameters

Parameter Type & Description
id required
string

ID of the base directory, relative to which the path remainder will be resolved. It can be a Space Id (in which case the space root directory is taken), or a File Id of any existing directory (including the space root directory). See Data section for more information.
path required
string

Path relative to the base directory (specified in the id parameter).

Query parameters

Parameter Type & Description
type
string

Type of the file.
posixPermissions
integer

POSIX file permissions in decimal format.
mode
integer

(deprecated) POSIX file permissions in decimal format.
create_parents
boolean

Allows to create unexistient directories specified in path parameter.
offset
integer

Offset at which the data sent as request body will be written to the file (relevant only if type == "REG").
target_file_id
string

The Id of the file to which the hard link should point (relevant only if type == "LNK").
target_file_path
string

Path to which the symbolic link should point (relevant only if type == "SYMLNK").

Request body

application/octet-stream

File content to be written at specified offset (relevant only if type == "REG").

No schema provided.

Request Examples

Shell
cat file.txt | oneprovider-rest-cli createFileAtPath id=$SPACE_OR_PARENT_ID path=$PATH -

Responses

application/json
201

The request has been accepted and the result is the file Id. Also URI of the file in form https://$PROVIDER_HOST/api/v3/oneprovider/data/{id} is returned in the response Location header.

PropertyType & Description
fileId
string

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

File not found.

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
    }
  }
}