API for Media Files

[jardakotesovec]

Endpoint overview

1. Get Media Files

GET /api/v1/submissions/{submissionId}/mediaFiles

Returns a list of media files for a submission.

Query Parameters:

• variantGroupIds (optional) - Array of integers to filter by variant group IDs
• variantTypes (optional) - Array of variant type strings (web or high_resolution)

Response:

{
  "itemsMax": 2,
  "items": [
    {
      "id": 1,
      "fileId": 100,
      "fileStage": 23,
      "name": {
        "en": "example-image.png"
      },
      "submissionId": 5,
      "variantGroupId": null,
      "variantType": "web"
    }
  ]
}

---

2. Add Media Files

POST /api/v1/submissions/{submissionId}/mediaFiles

Upload one or more media files from temporary file uploads.

Request Body:

{
  "files": [
    {
      "temporaryFileId": 123,
      "variantType": "web"
    },
    {
      "temporaryFileId": 124,
      "variantType": "high_resolution"
    }
  ]
}

Required Fields:

• files - Array of file objects (minimum 1)
• files[].temporaryFileId - Integer ID of the temporary file
• files[].variantType - String, must be web or high_resolution

Optional Fields:

• Any submission file properties (e.g., name, description, caption, etc.)

Response:

[
  {
    "id": 1,
    "fileId": 100,
    "fileStage": 23,
    "name": {
      "en": "example-image.png"
    },
    "submissionId": 5,
    "variantGroupId": null,
    "variantType": "web"
  }
]

---

3. Batch Link Media Files

POST /api/v1/submissions/{submissionId}/mediaFiles/link

Link or unlink multiple media file pairs in a single request.

Request Body:

{
  "links": [
    {
      "primarySubmissionFileId": 1,
      "secondarySubmissionFileId": 2
    },
    {
      "primarySubmissionFileId": 3,
      "secondarySubmissionFileId": null
    }
  ]
}

Required Fields:

• links - Array of link objects (minimum 1)
• links[].primarySubmissionFileId - Integer ID of the primary submission file

Optional Fields:

• links[].secondarySubmissionFileId - Integer ID of the secondary file to link, or null to unlink

Validation:

• Files cannot be linked to themselves
• Files must belong to the same submission
• Files must be media files (fileStage 23)
• Files must have different variant types
• Both files must have a variantType set

Response:

[
  {
    "id": 1,
    "fileId": 100,
    "fileStage": 23,
    "name": {
      "en": "image-web.png"
    },
    "submissionId": 5,
    "variantGroupId": 10,
    "variantType": "web"
  },
  {
    "id": 2,
    "fileId": 101,
    "fileStage": 23,
    "name": {
      "en": "image-high-res.tiff"
    },
    "submissionId": 5,
    "variantGroupId": 10,
    "variantType": "high_resolution"
  }
]

---

4. Link Single Media File

PUT /api/v1/submissions/{submissionId}/mediaFiles/{submissionFileId}/link

Link a media file to another file, creating or joining a variant group.

Request Body:

{
  "targetSubmissionFileId": 2
}

Required Fields:

• targetSubmissionFileId - Integer ID of the file to link to

Validation:

• File cannot be linked to itself
• Target file must exist and belong to the same submission
• Target file must be a media file (fileStage 23)
• Files must have different variant types
• Both files must have a variantType set

Response:

[
  {
    "id": 1,
    "fileId": 100,
    "fileStage": 23,
    "name": {
      "en": "image-web.png"
    },
    "submissionId": 5,
    "variantGroupId": 10,
    "variantType": "web"
  },
  {
    "id": 2,
    "fileId": 101,
    "fileStage": 23,
    "name": {
      "en": "image-high-res.tiff"
    },
    "submissionId": 5,
    "variantGroupId": 10,
    "variantType": "high_resolution"
  }
]

---

5. Edit Media File Metadata

PUT /api/v1/submissions/{submissionId}/mediaFiles/{submissionFileId}

Update metadata for a media file. If the file belongs to a variant group, common fields are applied to all files in the group.

Request Body:

{
  "caption": "A beautiful landscape photo",
  "credit": "Jane Photographer",
  "copyrightOwner": "Example Journal"
}

Allowed Fields:
Any submission file property except:

• submissionId
• fileId
• uploaderUserId
• createdAt
• fileStage

Common Fields (applied to all files in a variant group):

• name
• description
• caption
• credit
• copyrightOwner
• terms

Response:

{
  "id": 1,
  "fileId": 100,
  "fileStage": 23,
  "submissionId": 5,
  "caption": "A beautiful landscape photo",
  "credit": "Jane Photographer",
  "copyrightOwner": "Example Journal",
  "variantGroupId": 10,
  "variantType": "web"
}

---

6. Delete Media File

DELETE /api/v1/submissions/{submissionId}/mediaFiles/{submissionFileId}

Delete a media file and handle variant group cleanup.

Request Body:
None

Response:

{
  "id": 1,
  "fileId": 100,
  "fileStage": 23,
  "name": {
    "en": "deleted-image.jpg"
  },
  "submissionId": 5,
  "variantGroupId": 10,
  "variantType": "web"
}

Technical notes (as of 2026-02-13)

These notes are part of the initial planning for the feature and provide background on what went into the design.

Database

• Media files would be modelled as Submission Files, with new fileStage (something like SUBMISSION_FILE_MEDIA I think could work. And it would be connected to specific publication via assocId&assocType
• To be able to connect multiple files together (to link web to high resolution for example). We need to introduce some grouping mechanism. Good option seems to be introduce variant_group_id to the submission_files table. Which would result also in additional table with single column, just for tracking these id. We would not move metadata to the group.
• To be able to differentiate different types - we need some programatically readable types in the database. Option could be to add new variant_type, where we could use constants. We can just start with constants for web and high resolution. And having opened route to add more in future

API adjustments needed

• if groupId becomes available in the submissionId shape - that would be enough to group the files client side. Since the media section will have its own space - probably best not introduce pagination, which would make this more difficult.
• exposing variantType in submissionFile should be enough for indicating whether the file is web/high resolution
  ...

PRs:

• pkp-lib: pkp/pkp-lib#12251 API for Media Files #12306
• ojs: pkp/pkp-lib#12251 API for Media Files ojs#5325
• ops: pkp/pkp-lib#12251 API for Media Files ops#1205
• omp: pkp/pkp-lib#12251 API for Media Files omp#2237