Onedata API Reference

REST API references for Onezone, Oneprovider, and Onepanel.

Onezone REST API Oneprovider REST API Onepanel REST API

Create file in directory

POST /data/{id}/children

Creates a file in the directory specified by $PARENT_ID.

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

Create file

curl -H "X-Auth-Token: $TOKEN" \
-X POST "https://$PROVIDER_HOST/api/v3/oneprovider/data/$PARENT_ID/children?name=$NAME"
-H "Content-Type: application/octet-stream" -d "@file.dat"

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

Create directory

curl -H "X-Auth-Token: $TOKEN" \
-X POST "https://$PROVIDER_HOST/api/v3/oneprovider/data/$PARENT_ID/children?name=$NAME&type=DIR"

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

Create hard link

curl -H "X-Auth-Token: $TOKEN" \
-X POST "https://$PROVIDER_HOST/api/v3/oneprovider/data/$PARENT_ID/children?name=$NAME&type=LNK&target_file_id=$TARGET_FILE_ID"

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

Create symbolic link

curl -H "X-Auth-Token: $TOKEN" \
-X POST "https://$PROVIDER_HOST/api/v3/oneprovider/data/$PARENT_ID/children?name=$NAME&type=SYMLNK&target_file_path=$TARGET_FILE_PATH"

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

See also Create file at path.

Path parameters

Parameter Type & Description
id required
string

Id of the parent directory.

Query parameters

Parameter Type & Description
name required
string

Name of the file.
type
string

Type of the file.
posixPermissions
integer

POSIX file permissions in decimal format.
mode
integer

(deprecated) POSIX file permissions in decimal format.
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
oneprovider-rest-cli createFile id=$PARENT_ID name=$FILE_NAME

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