Metadata

Every item carries system metadata; you can attach your own custom key-value metadata on top.

Endpoints

Method	Path	Description	Permission
GET	/api/v1/containers/{container}/files/{fileId}	System metadata + custom metadata	files.read
GET	/api/v1/containers/{container}/files/{fileId}/metadata	Custom metadata only	metadata.read
PATCH	/api/v1/containers/{container}/files/{fileId}/metadata	Update custom metadata	metadata.write

System metadata

{
  "id": "file_8fK2...",
  "name": "agreement.pdf",
  "type": "file",
  "container": "contracts",
  "parentId": null,
  "sizeBytes": 482133,
  "contentType": "application/pdf",
  "createdAt": "2026-07-01T10:15:00Z",
  "modifiedAt": "2026-07-02T08:30:00Z",
  "eTag": "\"{E2A6...},2\"",
  "checksum": "q0FyZ2h..."
}

Custom metadata

Send a flat JSON object of string / number / boolean values. Set a key to null to remove it.

curl -X PATCH "https://storage.devd.org/api/v1/containers/contracts/files/file_XXXX/metadata" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "matterId": "MAT-10021",
    "documentType": "contract",
    "department": "legal",
    "retentionCategory": "seven-years"
  }'

Keys must start with a letter and contain only letters, digits, _ and - (max 64 chars, 32 keys per item, values up to 2000 characters).

Container metadata schemas

Your administrator can define a metadata schema per container. When a schema is defined, only the defined keys are accepted and values are type-checked (string / number / boolean / date); violations return METADATA_VALIDATION_FAILED. Keys mapped to native backend columns are also indexed by the storage backend where your administrator has enabled the mapping.