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 |
|---|---|---|
|
|
|
|
|
|
|
|
File metadata
Specifics
-
Without the
hashaparameter 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
| Name | Type | Description |
|---|---|---|
|
|
Add a content checksum to the response. Default |
POST /rest/v1/fs/targets/files/certificates/x.local.pem!metadata HTTP/1.1
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"size" : 3836,
"mtime" : "2026-07-01T16:47:31Z"
}
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
entriesfield 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
truncatedflag are returned. The value"truncated": truemeans the directory exceeds the boundary and recursive operations on it cannot be performed. -
The
removablefield 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
| Name | Type | Description |
|---|---|---|
|
|
Add a recursive summary for the entire subtree. Default |
POST /rest/v1/fs/targets/files/certificates/!metadata HTTP/1.1
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 }
}
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
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
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 }
}