Media File

1{
2  "schemaVersion": 1,
3  "domain": "media",
4  "entity": "media-file",
5  "displayName": "Media File",
6  "capability": "media.file",
7  "target": {
8    "classification": "native-plus-cms",
9    "nativeEntity": "Media Manager File",
10    "verifiedFqdn": null,
11    "idPolicy": "server-assigned",
12    "crosswalkRequired": true
13  },
14  "dependsOn": [],
15  "sourceAliases": [
16    {
17      "sourceSystem": "wordpress",
18      "sourceEntity": "attachment",
19      "routes": [
20        "/wp/v2/media"
21      ],
22      "confidence": "high"
23    },
24    {
25      "sourceSystem": "wix",
26      "sourceEntity": "mediaFile",
27      "routes": [
28        "Media Manager"
29      ],
30      "confidence": "high"
31    }
32  ],
33  "preferredWrite": {
34    "surface": "Media Manager Import",
35    "endpoint": "POST /site-media/v1/files/import",
36    "writerId": "importMedia",
37    "verification": "verified-live",
38    "importSafe": true,
39    "bulk": false
40  },
41  "fallbacks": [
42    {
43      "classification": "cms",
44      "when": "Use for attachment parent, captions, external source IDs, or metadata not represented by Media Manager."
45    }
46  ],
47  "reliability": {
48    "status": "partially-reliable",
49    "flags": []
50  },
51  "pitfalls": [
52    {
53      "code": "async-ready",
54      "severity": "blocker",
55      "summary": "Media import is asynchronous; poll until READY before referencing the file."
56    },
57    {
58      "code": "source-url-access",
59      "severity": "warning",
60      "summary": "Remote source URLs may expire or block hotlinking."
61    }
62  ],
63  "mappingGuidance": [
64    "Import referenced media by default; treat full-library import as explicit opt-in."
65  ],
66  "setupRequirements": [],
67  "evidence": [
68    {
69      "type": "wix-docs",
70      "url": "https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/file-descriptor-object",
71      "note": "object page (docs-survey sweep 2026-08-11)"
72    }
73    
74  ]
75}