Metadata (METADATA)

Overview

The METADATA method returns information about an object in JSON format: a file, a directory, or an entire section. Unlike HEAD, the information comes in the response body and does not require parsing headers; for a directory and a section, HEAD is not applicable at all.

Times in all responses are returned in UTC.

Request form

METADATA is a non-standard HTTP method, and the platform accepts it in two equivalent forms.

Directly by the METADATA method:

METADATA /rest/v1/fs/targets/files/report.pdf HTTP/1.1

By POST on a path with the !<method> suffix:

POST /rest/v1/fs/targets/files/report.pdf!metadata HTTP/1.1

The second form is suitable where a client or intermediate node does not pass non-standard methods. The suffix works at any nesting depth.

The request must not contain a body in either form: a request with a body is treated as a file upload and fails with 415 Unsupported Media Type.

Both forms also apply to other non-standard section methods — CLEAR, DOWNLOADZIP, UPLOADZIP.

Requests

HTTP verb Endpoint Description

METADATA

/rest/v1/fs/targets/<target>!metadata

Section metadata

METADATA

/rest/v1/fs/targets/<target>/<path>/!metadata

Directory metadata

METADATA

/rest/v1/fs/targets/<target>/<path>!metadata

File metadata


File metadata

Specifics

  • Without the hasha parameter the file content is not read, so the request is cheap regardless of file size.

  • Calculating a checksum requires reading the entire file. On files of hundreds of megabytes the request becomes expensive, so the parameter should be specified only when explicitly necessary — for example, when the user themself requested file verification.

Request

Table 1. Request parameters
Name Type Description

hasha

bool

Add a content checksum to the response. Default false.

Example request
POST /rest/v1/fs/targets/files/certificates/x.local.pem!metadata HTTP/1.1

Response

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "size" : 3836,
  "mtime" : "2026-07-01T16:47:31Z"
}
Example response with hasha=true
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "size" : 3836,
  "mtime" : "2026-07-01T16:47:31Z",
  "hasha" : "md5;9f86d081884c7d659a2feaa0c55ad015"
}

Directory metadata

Applicable to sections with tree structure.

Specifics

  • The entries field is counted for the current directory level without traversing nested ones: one directory pass, cost independent of tree depth.

  • A recursive summary is returned only on a request with deep=true.

  • Recursive traversal is limited by the same values as recursive deletion: 10,000 files and 10 GB. On reaching the boundary, traversal stops, accumulated values and the truncated flag are returned. The value "truncated": true means the directory exceeds the boundary and recursive operations on it cannot be performed.

  • The removable field takes into account the domain type, role restrictions, and the fact that the section root cannot be deleted. The application uses it to decide whether to show the delete action.

Request

Table 2. Request parameters
Name Type Description

deep

bool

Add a recursive summary for the entire subtree. Default false.

Example request
POST /rest/v1/fs/targets/files/certificates/!metadata HTTP/1.1

Response

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "type" : "directory",
  "path" : "certificates",
  "last_modified" : "2026-07-20T10:21:06Z",
  "entries" : { "files" : 128, "directories" : 3 },
  "writable" : true,
  "removable" : true,
  "macro" : null,
  "public_url" : null,
  "limits" : { "max_file_size" : 536870912 }
}
Example response with deep=true
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "type" : "directory",
  "path" : "certificates",
  "last_modified" : "2026-07-20T10:21:06Z",
  "entries" : { "files" : 128, "directories" : 3 },
  "total" : { "files" : 4120, "directories" : 87, "bytes" : 1841207332, "truncated" : false },
  "writable" : true,
  "removable" : true,
  "limits" : { "max_file_size" : 536870912 }
}

Section metadata

Returns the section description — the same as in the section descriptions — supplemented with information about the current root state.

Request

Example request
POST /rest/v1/fs/targets/files!metadata HTTP/1.1

For sections with a path parameter, the parameter value is specified before the suffix:

POST /rest/v1/fs/targets/cpd_templates/ivr!metadata HTTP/1.1

Response

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "name" : "files",
  "url" : "/rest/v1/fs/targets/files",
  "title" : "Domain files",
  "structure" : "tree",
  "methods" : {
    "collection" : [ "GET", "POST", "METADATA", "CLEAR", "DOWNLOADZIP", "UPLOADZIP" ],
    "item" : [ "GET", "HEAD", "POST", "PUT", "DELETE", "METADATA" ],
    "directory" : [ "GET", "METADATA", "PUT", "DELETE", "CLEAR", "DOWNLOADZIP", "UPLOADZIP" ]
  },
  "writable" : true,
  "exists" : true,
  "entries" : { "files" : 12, "directories" : 4 }
}