Metadata & MDF API

CRITICAL WARNING — DO NOT USE MDF ENDPOINTS WITHOUT EXTREME CAUTION

The MDF (Metadata Definition Form) endpoints are DESTRUCTIVE. Writing to these endpoints — including POST, PUT, PATCH, and DELETE — can cause complete loss of all metadata across the entire Mimir instance. Even seemingly read-safe operations like GET may trigger side effects in combination with write operations. Do not probe, test, or call these endpoints against a production instance. Any automated tooling must explicitly exclude /api/v1/mdfs and /api/v1/optionLists paths.

10 confirmed endpoints — 6 respond with data, 4 require valid input.

Endpoints with Response Data

GET /api/v1/mdfs

Retrieve MDF entries

✅ Live — responds with data

Read-only but handle with care

While GET is read-only, the response contains the full MDF configuration. Do not use the response payload as input to PUT/POST without fully understanding the consequences — overwriting MDFs can destroy all item metadata.

Sample Response:

{
  "_embedded": {
    "collection": [
      {
        "active": true,
        "id": "default",
        "label": "Common",
        "modifiedOn": "2026-04-02T21:58:53.112Z"
      },
      {
        "active": true,
        "flavor": "technical_data",
        "id": "default_audio",
        "label": "Audio items",
        "modifiedOn": "2026-03-09T15:55:11.239Z"
      },
      {
        "active": true,
        "color": "#FB8C00FF",
        "flavor": "timed-metadata",
        "icon": "short_text",
        "id": "default_detected_text",
        "label": "Detected Text",
        "modifiedOn": "2026-03-31T17:34:45.155Z",
        "rule": "{text}"
      },
      {
        "active": true,
        "id": "default_folder",
        "label": "Folder Common",
        "modifiedOn": "2025-10-15T05:21:00.967Z"
      },
      {
        "active": true,
        "flavor": "technical_data",
        "id": "default_image",
        "label": "Image items",
        "modifiedOn": "2026-03-09T15:55:12.314Z"
      },
      {
        "active": true,
        "color": "#FB8C00FF",
        "flavor": "timed-metadata",
        "icon": "warning",
        "id": "default_restricted",
        "label": "Restricted Material",
        "modifiedOn": "2026-03-31T15:59:57.293Z",
        "usageRules": [
          {
            "identifier": {
              "key": "Pool Feeds",
              "label": "Pool Feeds"
            },
            "contexts": [
              {
                "name": "No promo use",
                "warningLevel": "always",
                "validity": {
                  "from": {
                    "offsetFrom": "forever"
                  },
                  "to": {
                    "offsetFrom": "forever"
                  }
                }
              }
            ]
          }
        ]
      },
      {
        "active": true,
        "flavor": "technical_data",
        "id": "default_video",
        "label": "Video items",
        "modifiedOn": "2026-03-09T15:55:09.879Z"
      }
    ]
  }
}

Response Schema:

Field	Type	Required
_embedded	object	Yes

---

POST /api/v1/mdfs

Create an MDF entry

✅ Live — responds with data

DESTRUCTIVE — Creates MDF definitions that affect all items. May cause metadata loss.

Sample Response:

{
  "flavor": "timed-metadata",
  "label": "Artist",
  "active": false,
  "id": "95411dce-9a8e-459a-97a7-8e0570526d85",
  "displayName": "Recording Artists",
  "fields": []
}

Response Schema:

Field	Type	Required
active	boolean	Yes
displayName	string	Yes
fields	array	Yes
flavor	string	Yes
id	string	Yes
label	string	Yes

---

GET /api/v1/mdfs/{mdfId}

Retrieve an MDF entry

✅ Live — responds with data

Response keys: fields, active, modifiedOn, label, views, permissions, viewSections, id

Response Schema:

Field	Type	Required
active	boolean	Yes
color	string	No
displayName	string	No
fields	array	Yes
flavor	string	No
icon	string	No
id	string	Yes
label	string	Yes
rule	string	No
viewSections	object	Yes
views	object	Yes

---

PUT /api/v1/mdfs/{mdfId}

Update an MDF entry

✅ Live — responds with data

HIGHLY DESTRUCTIVE — Overwrites MDF definitions. Can cause complete loss of all item metadata across the instance.

Sample Response:

{
  "fields": [
    {
      "id": "default_title",
      "fieldId": "title",
      "type": "text",
      "required": false,
      "systemDefaultField": true,
      "readOnly": false,
      "sortable": false
    },
    {
      "id": "default_description",
      "fieldId": "description",
      "type": "text",
      "required": false,
      "systemDefaultField": true,
      "readOnly": false,
      "sortable": false
    },
    {
      "id": "default_createdOn",
      "fieldId": "createdOn",
      "type": "date",
      "required": false,
      "systemDefaultField": true,
      "readOnly": false,
      "sortable": false
    },
    {
      "id": "default_mediaCreatedOn",
      "fieldId": "mediaCreatedOn",
      "type": "date",
      "required": false,
      "systemDefaultField": true,
      "readOnly": false,
      "sortable": false
    },
    {
      "id": "aaa4c91e-191a-470d-9a15-9fe759503266",
      "fieldId": "name",
      "type": "text",
      "required": false
    },
    {
      "id": "ea129745-8d12-4ad8-9643-c0ae09fac573",
      "fieldId": "genre",
      "type": "choice",
      "defaultValue": "Rock",
      "required": false,
      "alternatives": [
        {
          "value": "Rock",
          "label": "Rock"
        },
        {
          "value": "Blues",
          "label": "Blues"
        }
      ]
    }
  ],
  "active": true,
  "modifiedOn": "2026-04-02T21:58:53.112Z",
  "label": "Common",
  "views": {},
  "permissions": {
    "read": {},
    "write": {}
  },
  "viewSections": {},
  "id": "default",
  "rule": "{name}-{genre}",
  "icon": "radio",
  "color": "#008DFFFF",
  "displayName": "Recording Artists"
}

Response Schema:

Field	Type	Required
active	boolean	Yes
color	string	Yes
displayName	string	Yes
fields	array	Yes
icon	string	Yes
id	string	Yes
label	string	Yes
modifiedOn	string	Yes
permissions	object	Yes
rule	string	Yes
viewSections	object	Yes
views	object	Yes

---

POST /api/v1/optionLists

Create an option list

✅ Live — responds with data

DESTRUCTIVE — Modifying option lists affects metadata field choices across all items.

Sample Response:

{
  "id": "85ab3a55-6083-493d-960f-cb1130311081",
  "name": "test-name",
  "optionListType": "choice",
  "alternatives": [],
  "modifiedOn": "2026-04-07T01:59:54.047Z"
}

Response Schema:

Field	Type	Required
alternatives	array	Yes
id	string	Yes
modifiedOn	string	Yes
name	string	Yes
optionListType	string	Yes

---

DELETE /api/v1/optionLists/{optionListId}

Delete an option list

✅ Live — responds with data

DESTRUCTIVE — Deleting option lists removes metadata field choices permanently.

---

Endpoints Requiring Valid Input

These endpoints are confirmed live but need proper request bodies.

PATCH /api/v1/itemMetadata/{id}

Partially update itemMetadata

⚠️ Live — requires valid request body

Query Parameters:

Name	Example
requiredMetadataVersion	1
readableMetadataFields	false

Note

mimir-client.ts — update IPTC tags

---

DELETE /api/v1/mdfs/{mdfId}

Delete an MDF entry

⚠️ Live — requires valid request body

HIGHLY DESTRUCTIVE — Deleting an MDF removes metadata definitions and can cause permanent data loss across all items.

Sample Response:

{
  "error": {
    "statusCode": 400,
    "message": "Cannot delete default form"
  }
}

Response Schema:

Field	Type	Required
error	object	Yes

Note

[400] {'statusCode': 400, 'message': 'Cannot delete default form'}

---

GET /api/v1/optionLists

Retrieve option lists

Live — status 502

Note

[502] Internal server error

---

PUT /api/v1/optionLists/{optionListId}

Update an option list

Live — status 403

DESTRUCTIVE — Overwriting option lists affects metadata field choices across all items.

Sample Response:

{
  "error": {
    "statusCode": 403,
    "message": "Name 'test-name' is already used by another option list"
  }
}

Response Schema:

Field	Type	Required
error	object	Yes

Note

[403] {'statusCode': 403, 'message': "Name 'test-name' is already used by another option list"}

---

Not Found

Method	Path	Code
GET	/api/v1/metadata	404
GET	/api/v1/metadata/fields	404
GET	/api/v1/metadata/forms	404
GET	/api/v1/metadata/forms/{formId}	404
GET	/api/v1/metadataDefinitions	404
GET	/api/v1/optionLists/{listId}	404
GET	/api/v1/optionLists/{optionListId}	404