{
  "openapi": "3.0.3",
  "info": {
    "title": "Medialit API",
    "description": "Easy file uploads for serverless apps",
    "version": "0.3.0",
    "termsOfService": "https://medialit.cloud/p/terms",
    "contact": {
      "name": "Medialit Support",
      "url": "https://medialit.cloud"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://www.gnu.org/licenses/agpl-3.0.en.html"
    }
  },
  "servers": [
    {
      "url": "{protocol}://{host}",
      "description": "API Server",
      "variables": {
        "protocol": {
          "default": "https",
          "enum": [
            "https",
            "http"
          ]
        },
        "host": {
          "default": "api.medialit.cloud"
        }
      }
    }
  ],
  "tags": [
    {
      "name": "Media",
      "description": "Upload, list, and manage media resources."
    },
    {
      "name": "Settings",
      "description": "Manage media processing configuration."
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Status of the server",
        "description": "Returns the status of the server and uptime",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ok"
                    },
                    "uptime": {
                      "type": "number",
                      "example": 12.345
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "getHealth",
        "security": []
      }
    },
    "/settings/media/create": {
      "post": {
        "tags": [
          "Settings"
        ],
        "summary": "Update Media Settings",
        "description": "Update configuration for media processing.",
        "responses": {
          "200": {
            "description": "Settings updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "success"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Bad Request"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden"
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Internal Server Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MediaSettingsPayload"
              }
            }
          }
        },
        "operationId": "updateMediaSettings"
      }
    },
    "/settings/media/get": {
      "post": {
        "tags": [
          "Settings"
        ],
        "summary": "Get Media Settings",
        "description": "Retrieve current media processing configuration.",
        "responses": {
          "200": {
            "description": "Settings retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaSettings"
                }
              }
            }
          },
          "400": {
            "description": "More than one credential was sent, for example both a Bearer token and an API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "credential_ambiguous",
                  "error_description": "Exactly one credential mechanism is allowed."
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden"
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Internal Server Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "operationId": "getMediaSettings"
      }
    },
    "/media/signature/create": {
      "post": {
        "tags": [
          "Media"
        ],
        "summary": "Create Upload Signature",
        "description": "Generate a signature for secure client-side uploads.",
        "responses": {
          "200": {
            "description": "Signature generated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignatureResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Bad Request"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden"
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Internal Server Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "operationId": "createUploadSignature"
      }
    },
    "/media/create": {
      "post": {
        "tags": [
          "Media"
        ],
        "summary": "Upload Media",
        "description": "Upload a new media file. Use OAuth Bearer auth, API key auth from Authorize (`x-medialit-apikey`), or pass `x-medialit-signature` for this endpoint only.",
        "parameters": [
          {
            "name": "x-medialit-signature",
            "in": "header",
            "description": "Upload Signature for secure client-side uploads",
            "schema": {
              "type": "string"
            },
            "required": false
          }
        ],
        "responses": {
          "200": {
            "description": "The created Media object",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Media"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Bad Request"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Unauthorized"
                }
              }
            }
          },
          "404": {
            "description": "Invalid signature",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Invalid signature"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Internal Server Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          },
          {
            "signatureAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  },
                  "caption": {
                    "type": "string"
                  },
                  "access": {
                    "type": "string",
                    "enum": [
                      "public",
                      "private"
                    ]
                  },
                  "group": {
                    "type": "string"
                  }
                },
                "required": [
                  "file"
                ]
              }
            }
          }
        },
        "operationId": "uploadMedia"
      }
    },
    "/media/get/count": {
      "post": {
        "tags": [
          "Media"
        ],
        "summary": "Get Media Count",
        "description": "Get the total number of media files.",
        "responses": {
          "200": {
            "description": "Count retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaCountResponse"
                }
              }
            }
          },
          "400": {
            "description": "More than one credential was sent, for example both a Bearer token and an API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "credential_ambiguous",
                  "error_description": "Exactly one credential mechanism is allowed."
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden"
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Internal Server Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "operationId": "getMediaCount"
      }
    },
    "/media/get/size": {
      "post": {
        "tags": [
          "Media"
        ],
        "summary": "Get Total Size",
        "description": "Get the total size of all media files in bytes.",
        "responses": {
          "200": {
            "description": "Size retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaSizeResponse"
                }
              }
            }
          },
          "400": {
            "description": "More than one credential was sent, for example both a Bearer token and an API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "credential_ambiguous",
                  "error_description": "Exactly one credential mechanism is allowed."
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden"
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Internal Server Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "operationId": "getMediaSize"
      }
    },
    "/media/get/{mediaId}": {
      "post": {
        "tags": [
          "Media"
        ],
        "summary": "Get Media Details",
        "description": "Retrieve metadata for a specific media item.",
        "parameters": [
          {
            "name": "mediaId",
            "in": "path",
            "required": true,
            "description": "ID of the media file",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Media details retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Media"
                }
              }
            }
          },
          "400": {
            "description": "More than one credential was sent, for example both a Bearer token and an API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "credential_ambiguous",
                  "error_description": "Exactly one credential mechanism is allowed."
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Media not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Not Found"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Internal Server Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "operationId": "getMediaDetails"
      }
    },
    "/media/get": {
      "post": {
        "tags": [
          "Media"
        ],
        "summary": "List Media",
        "description": "List media files filtered by optional query payload.",
        "responses": {
          "200": {
            "description": "List retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/MediaListItem"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Bad Request"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden"
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Internal Server Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GetMediaQuery"
              }
            }
          }
        },
        "operationId": "listMedia"
      }
    },
    "/media/seal/{mediaId}": {
      "post": {
        "tags": [
          "Media"
        ],
        "summary": "Seal Media",
        "description": "Seal a media file (mark as processed/finalized).",
        "parameters": [
          {
            "name": "mediaId",
            "in": "path",
            "required": true,
            "description": "ID of the media file",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The created Media object",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Media"
                }
              }
            }
          },
          "400": {
            "description": "More than one credential was sent, for example both a Bearer token and an API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "credential_ambiguous",
                  "error_description": "Exactly one credential mechanism is allowed."
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Media not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Not Found"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Internal Server Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "operationId": "sealMedia"
      }
    },
    "/media/delete/{mediaId}": {
      "delete": {
        "tags": [
          "Media"
        ],
        "summary": "Delete Media",
        "description": "Permanently delete a media file.",
        "parameters": [
          {
            "name": "mediaId",
            "in": "path",
            "required": true,
            "description": "ID of the media file",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Media deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "success"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "More than one credential was sent, for example both a Bearer token and an API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "credential_ambiguous",
                  "error_description": "Exactly one credential mechanism is allowed."
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden"
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Internal Server Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "operationId": "deleteMedia"
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-medialit-apikey"
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      },
      "signatureAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-medialit-signature"
      }
    },
    "schemas": {
      "Media": {
        "type": "object",
        "properties": {
          "mediaId": {
            "type": "string"
          },
          "originalFileName": {
            "type": "string"
          },
          "mimeType": {
            "type": "string"
          },
          "size": {
            "type": "number",
            "format": "float"
          },
          "access": {
            "type": "string",
            "enum": [
              "public",
              "private"
            ]
          },
          "file": {
            "type": "string"
          },
          "thumbnail": {
            "type": "string"
          },
          "caption": {
            "type": "string"
          },
          "group": {
            "type": "string"
          }
        },
        "required": [
          "mediaId",
          "originalFileName",
          "mimeType",
          "size",
          "access",
          "file"
        ],
        "additionalProperties": false
      },
      "MediaListItem": {
        "type": "object",
        "properties": {
          "mediaId": {
            "type": "string"
          },
          "originalFileName": {
            "type": "string"
          },
          "mimeType": {
            "type": "string"
          },
          "size": {
            "type": "number",
            "format": "float"
          },
          "access": {
            "type": "string",
            "enum": [
              "public",
              "private"
            ]
          },
          "thumbnail": {
            "type": "string"
          },
          "caption": {
            "type": "string"
          },
          "group": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "mediaId",
          "originalFileName",
          "mimeType",
          "size",
          "access",
          "createdAt"
        ],
        "additionalProperties": false
      },
      "MediaSettings": {
        "type": "object",
        "properties": {
          "useWebP": {
            "type": "boolean"
          },
          "webpOutputQuality": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "maximum": 100
          },
          "thumbnailWidth": {
            "type": "number",
            "format": "float",
            "minimum": 1
          },
          "thumbnailHeight": {
            "type": "number",
            "format": "float",
            "minimum": 1
          }
        },
        "additionalProperties": false
      },
      "MediaSettingsPayload": {
        "type": "object",
        "properties": {
          "useWebP": {
            "type": "boolean"
          },
          "webpOutputQuality": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "maximum": 100
          },
          "thumbnailWidth": {
            "type": "number",
            "format": "float",
            "minimum": 1
          },
          "thumbnailHeight": {
            "type": "number",
            "format": "float",
            "minimum": 1
          }
        },
        "additionalProperties": false
      },
      "UploadMediaPayload": {
        "type": "object",
        "properties": {
          "caption": {
            "type": "string"
          },
          "access": {
            "type": "string",
            "enum": [
              "public",
              "private"
            ]
          },
          "group": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "GetMediaQuery": {
        "type": "object",
        "properties": {
          "page": {
            "type": "number",
            "format": "float",
            "minimum": 1
          },
          "limit": {
            "type": "number",
            "format": "float",
            "minimum": 1
          },
          "access": {
            "type": "string",
            "enum": [
              "public",
              "private"
            ]
          },
          "group": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "SignatureResponse": {
        "type": "object",
        "properties": {
          "signature": {
            "type": "string",
            "description": "HMAC signature for secure uploads"
          }
        },
        "required": [
          "signature"
        ],
        "additionalProperties": false
      },
      "MediaCountResponse": {
        "type": "object",
        "properties": {
          "count": {
            "type": "number",
            "format": "float"
          }
        },
        "required": [
          "count"
        ],
        "additionalProperties": false
      },
      "MediaSizeResponse": {
        "type": "object",
        "properties": {
          "storage": {
            "type": "number",
            "format": "float"
          },
          "maxStorage": {
            "type": "number",
            "format": "float"
          }
        },
        "required": [
          "storage",
          "maxStorage"
        ],
        "additionalProperties": false
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "Unauthorized"
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false
      }
    }
  }
}