{
    "openapi": "3.1.2",
    "info": {
        "title": "Media2URL Developer Platform REST API",
        "version": "1.0.0",
        "description": "Official REST API for Media2URL external developers and authenticated automation clients. Provides direct Cloudflare R2 presigned file uploads with temporary-to-final object promotion, transactional quota reservations, asset management, version history, duplicate detection, and remote URL imports.",
        "contact": {
            "name": "Media2URL Developer Platform",
            "url": "https://media2url.com/contact",
            "email": "[email protected]"
        },
        "license": {
            "name": "Proprietary",
            "url": "https://media2url.com/terms"
        }
    },
    "servers": [
        {
            "url": "https://api.media2url.com/v1",
            "description": "Production API v1"
        }
    ],
    "security": [
        {
            "BearerAuth": []
        }
    ],
    "paths": {
        "/usage": {
            "get": {
                "operationId": "getUsage",
                "summary": "Retrieve Account & API Usage",
                "description": "Returns authoritative usage metrics for storage, bandwidth, and monthly upload counts.",
                "security": [
                    {
                        "BearerAuth": [
                            "usage:read"
                        ]
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Authoritative usage metrics",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/UsageResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/uploads/presign": {
            "post": {
                "operationId": "presignUpload",
                "summary": "Request Direct R2 Upload URL",
                "description": "Validates file metadata against account quotas, atomically reserves storage capacity, and generates a short-lived presigned PUT URL targeting a temporary R2 key.",
                "security": [
                    {
                        "BearerAuth": [
                            "uploads:write"
                        ]
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PresignUploadRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Temporary upload URL generated",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PresignUploadResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/BadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/uploads/finalize": {
            "post": {
                "operationId": "finalizeUpload",
                "summary": "Finalize Upload & Promote Asset",
                "description": "Atomically consumes the upload session, validates temporary R2 object size, content type, magic bytes, and blocked fingerprints, promotes the validated bytes into a non-presigned final key, commits quota, and returns the canonical asset links.",
                "security": [
                    {
                        "BearerAuth": [
                            "uploads:write"
                        ]
                    }
                ],
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "maxLength": 128
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/FinalizeUploadRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Asset created and promoted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/AssetResource"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/BadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "409": {
                        "$ref": "#/components/responses/Conflict"
                    },
                    "410": {
                        "$ref": "#/components/responses/Gone"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/uploads/check-duplicate": {
            "post": {
                "operationId": "checkDuplicate",
                "summary": "Check for Duplicate Asset",
                "description": "Searches within the authenticated account's scope for an existing asset matching the given SHA-256 checksum and optional byte size.",
                "security": [
                    {
                        "BearerAuth": [
                            "assets:read"
                        ]
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CheckDuplicateRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Duplicate detection result",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/CheckDuplicateResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/BadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    }
                }
            }
        },
        "/assets": {
            "get": {
                "operationId": "listAssets",
                "summary": "List Assets",
                "description": "Returns a cursor-paginated list of assets owned by the authenticated account.",
                "security": [
                    {
                        "BearerAuth": [
                            "assets:read"
                        ]
                    }
                ],
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 20,
                            "maximum": 100
                        }
                    },
                    {
                        "name": "cursor"
                    }
                ]
            }
        }
    },
    "_note": "Response truncated for documentation purposes"
}