{
    "openapi": "3.1.0",
    "info": {
        "title": "Media Processing API",
        "version": "v1",
        "description": "Asynchronous video, image and audio processing: scale, compress, watermark, thumbnails, course videos and audio tracks, with signed callbacks."
    },
    "servers": [
        {
            "url": "https://api.flowdata.one/v1",
            "description": "FlowData API"
        }
    ],
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "tags": [
        {
            "name": "pipelines",
            "description": "Pipelines & presets"
        },
        {
            "name": "jobs",
            "description": "Jobs"
        },
        {
            "name": "assets",
            "description": "Watermarks"
        },
        {
            "name": "callbacks",
            "description": "Callbacks (webhooks)"
        }
    ],
    "paths": {
        "/media/presets": {
            "get": {
                "operationId": "presets-list",
                "summary": "List presets",
                "description": "All system pipelines (system: true) and the presets of your team.",
                "tags": [
                    "pipelines"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "data": [
                                        {
                                            "key": "ugc_video",
                                            "system": true,
                                            "pipeline": "ugc_video",
                                            "outputs": [
                                                "watermarked",
                                                "clean",
                                                "thumbnail"
                                            ]
                                        },
                                        {
                                            "key": "ugc_hd",
                                            "system": false,
                                            "name": "UGC in HD",
                                            "pipeline": "ugc_video",
                                            "options": {
                                                "width": 720,
                                                "height": 1280
                                            },
                                            "outputs": {
                                                "clean": {
                                                    "crf": 20
                                                }
                                            },
                                            "updated_at": "2026-09-28T10:00:00Z"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Error response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "operationId": "presets-store",
                "summary": "Create or replace a preset",
                "description": "Creates a team preset (201) or replaces one with the same key (200). System names are reserved.",
                "tags": [
                    "pipelines"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "key": "ugc_hd",
                                    "system": false,
                                    "name": "UGC in HD",
                                    "pipeline": "ugc_video",
                                    "options": {
                                        "width": 720,
                                        "height": 1280,
                                        "watermark": {
                                            "asset": "brand_white",
                                            "opacity": 0.3
                                        }
                                    },
                                    "outputs": {
                                        "clean": {
                                            "crf": 20
                                        }
                                    },
                                    "updated_at": "2026-09-28T10:00:00Z"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Error response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "key": {
                                        "type": "string",
                                        "description": "1 to 64 characters from a-z, 0-9, _ and -"
                                    },
                                    "name": {
                                        "type": "string",
                                        "description": "Label, at most 191 characters"
                                    },
                                    "pipeline": {
                                        "type": "string",
                                        "description": "Base pipeline, for example ugc_video"
                                    },
                                    "options": {
                                        "type": "object",
                                        "description": "Options for all outputs including watermark"
                                    },
                                    "outputs": {
                                        "type": "object",
                                        "description": "Overrides per output name"
                                    }
                                },
                                "required": [
                                    "key",
                                    "pipeline"
                                ]
                            },
                            "example": {
                                "key": "ugc_hd",
                                "name": "UGC in HD",
                                "pipeline": "ugc_video",
                                "options": {
                                    "width": 720,
                                    "height": 1280,
                                    "watermark": {
                                        "asset": "brand_white",
                                        "opacity": 0.3
                                    }
                                },
                                "outputs": {
                                    "clean": {
                                        "crf": 20
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/media/presets/{key}": {
            "delete": {
                "operationId": "presets-delete",
                "summary": "Delete a preset",
                "description": "Deletes a team preset. Jobs already created are not affected, they carry a copy of their settings.",
                "tags": [
                    "pipelines"
                ],
                "parameters": [
                    {
                        "name": "key",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "deleted": true,
                                    "key": "ugc_hd"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Error response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/media/jobs": {
            "post": {
                "operationId": "jobs-create",
                "summary": "Create a job",
                "description": "Creates a job and answers with 202 and queue_position. Exactly one of pipeline and preset, exactly one of input.url and input.upload_id, for each output exactly one of put_url and managed: true. All URLs must be https and point to public addresses.",
                "tags": [
                    "jobs"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "id": "01J8Z6Q4T0M3S1V7B2X9K5N4RD",
                                    "status": "queued",
                                    "pipeline": "ugc_video",
                                    "reference": "orderfile:12345",
                                    "priority": "normal",
                                    "outputs": {
                                        "watermarked": {
                                            "status": "pending",
                                            "target": "put"
                                        },
                                        "clean": {
                                            "status": "pending",
                                            "target": "managed",
                                            "download_url": null,
                                            "expires_at": null
                                        },
                                        "thumbnail": {
                                            "status": "pending",
                                            "target": "put"
                                        }
                                    },
                                    "error": null,
                                    "queue_position": 1
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Error response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "pipeline": {
                                        "type": "string",
                                        "description": "System pipeline (see table), alternatively preset"
                                    },
                                    "preset": {
                                        "type": "string",
                                        "description": "Key of a team preset, alternatively pipeline"
                                    },
                                    "reference": {
                                        "type": "string",
                                        "description": "Your own reference (at most 191 characters), queryable through GET /jobs?reference="
                                    },
                                    "priority": {
                                        "type": "string",
                                        "description": "high, normal (default) or low; course_video defaults to low"
                                    },
                                    "input": {
                                        "type": "object",
                                        "properties": {
                                            "url": {
                                                "type": "string",
                                                "description": "Public https URL of the source, up to 3 redirects"
                                            },
                                            "upload_id": {
                                                "type": "string",
                                                "description": "ID from POST /uploads, usable once"
                                            },
                                            "filename": {
                                                "type": "string",
                                                "description": "Original file name (display only)"
                                            },
                                            "size": {
                                                "type": "integer",
                                                "description": "Size in bytes; checked against the limit up front and improves the cost reservation"
                                            }
                                        }
                                    },
                                    "outputs": {
                                        "type": "object",
                                        "properties": {
                                            "<name>.put_url": {
                                                "type": "string",
                                                "description": "Presigned PUT URL for the result"
                                            },
                                            "<name>.managed": {
                                                "type": "boolean",
                                                "description": "true: we store the result for 7 days"
                                            },
                                            "<name>.content_type": {
                                                "type": "string",
                                                "description": "Content-Type for the PUT, default matching the format"
                                            },
                                            "<name>.*": {
                                                "type": "object",
                                                "description": "Overrides such as width, height, fit, crf, format, quality, watermark"
                                            }
                                        }
                                    },
                                    "options": {
                                        "type": "object",
                                        "description": "Options for all outputs, including watermark.asset"
                                    },
                                    "callback": {
                                        "type": "object",
                                        "properties": {
                                            "endpoint_id": {
                                                "type": "string",
                                                "description": "ID of a registered webhook endpoint"
                                            },
                                            "url": {
                                                "type": "string",
                                                "description": "Free https URL; signed with the secret of the default endpoint, otherwise unsigned"
                                            },
                                            "events": {
                                                "type": "array",
                                                "items": [],
                                                "description": "job.finished and/or job.failed (default: both)"
                                            }
                                        }
                                    },
                                    "metadata": {
                                        "type": "object",
                                        "description": "Any JSON up to 4 KB, returned unchanged in the callback"
                                    }
                                }
                            },
                            "example": {
                                "pipeline": "ugc_video",
                                "reference": "orderfile:12345",
                                "input": {
                                    "url": "https://files.example.com/in/abc.mov?X-Amz-Signature=…",
                                    "filename": "abc.mov"
                                },
                                "outputs": {
                                    "watermarked": {
                                        "put_url": "https://uploads.example.com/out/wm.mp4?X-Amz-Signature=…"
                                    },
                                    "clean": {
                                        "managed": true
                                    },
                                    "thumbnail": {
                                        "put_url": "https://uploads.example.com/out/thumb.jpg?X-Amz-Signature=…"
                                    }
                                },
                                "options": {
                                    "watermark": {
                                        "asset": "brand_white"
                                    }
                                },
                                "callback": {
                                    "endpoint_id": "01J8Z6Q4T0M3S1V7B2X9K5N4WH"
                                },
                                "metadata": {
                                    "entity": "order_file"
                                }
                            }
                        }
                    }
                }
            },
            "get": {
                "operationId": "jobs-by-reference",
                "summary": "Find jobs by reference",
                "description": "The up to 20 newest jobs with this reference.",
                "tags": [
                    "jobs"
                ],
                "parameters": [
                    {
                        "name": "reference",
                        "in": "query",
                        "required": true,
                        "description": "Your reference from POST /jobs",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "data": [
                                        {
                                            "id": "01J8Z6Q4T0M3S1V7B2X9K5N4RD",
                                            "status": "finished",
                                            "pipeline": "ugc_video",
                                            "preset": null,
                                            "reference": "orderfile:12345",
                                            "priority": "normal",
                                            "created_at": "2026-09-28T10:00:00Z",
                                            "started_at": "2026-09-28T10:00:02Z",
                                            "finished_at": "2026-09-28T10:00:31Z",
                                            "input": {
                                                "size": 48211234,
                                                "duration": 27.4,
                                                "width": 1080,
                                                "height": 1920,
                                                "video_codec": "hevc",
                                                "has_audio": true
                                            },
                                            "outputs": {
                                                "watermarked": {
                                                    "status": "uploaded",
                                                    "target": "put",
                                                    "size": 6123456,
                                                    "width": 540,
                                                    "height": 960,
                                                    "duration": 27.4,
                                                    "sha256": "9f2c…"
                                                },
                                                "clean": {
                                                    "status": "uploaded",
                                                    "target": "managed",
                                                    "size": 6101234,
                                                    "width": 540,
                                                    "height": 960,
                                                    "duration": 27.4,
                                                    "sha256": "4b1a…",
                                                    "download_url": "https://…",
                                                    "expires_at": "2026-10-05T10:00:31Z"
                                                }
                                            },
                                            "options": {
                                                "watermark": {
                                                    "asset": "brand_white",
                                                    "asset_sha256": "c0ff…"
                                                }
                                            },
                                            "error": null,
                                            "processing_seconds": 28.6,
                                            "cancel_requested": false
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Error response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/media/jobs/{job_id}": {
            "get": {
                "operationId": "jobs-show",
                "summary": "Get a job",
                "description": "Returns the job in the same shape as the callback. For managed outputs download_url carries a signed link valid until expires_at.",
                "tags": [
                    "jobs"
                ],
                "parameters": [
                    {
                        "name": "job_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "id": "01J8Z6Q4T0M3S1V7B2X9K5N4RD",
                                    "status": "finished",
                                    "pipeline": "ugc_video",
                                    "preset": null,
                                    "reference": "orderfile:12345",
                                    "priority": "normal",
                                    "created_at": "2026-09-28T10:00:00Z",
                                    "started_at": "2026-09-28T10:00:02Z",
                                    "finished_at": "2026-09-28T10:00:31Z",
                                    "input": {
                                        "size": 48211234,
                                        "duration": 27.4,
                                        "width": 1080,
                                        "height": 1920,
                                        "video_codec": "hevc",
                                        "has_audio": true
                                    },
                                    "outputs": {
                                        "watermarked": {
                                            "status": "uploaded",
                                            "target": "put",
                                            "size": 6123456,
                                            "width": 540,
                                            "height": 960,
                                            "duration": 27.4,
                                            "sha256": "9f2c…"
                                        },
                                        "clean": {
                                            "status": "uploaded",
                                            "target": "managed",
                                            "size": 6101234,
                                            "width": 540,
                                            "height": 960,
                                            "duration": 27.4,
                                            "sha256": "4b1a…",
                                            "download_url": "https://…",
                                            "expires_at": "2026-10-05T10:00:31Z"
                                        }
                                    },
                                    "options": {
                                        "watermark": {
                                            "asset": "brand_white",
                                            "asset_sha256": "c0ff…"
                                        }
                                    },
                                    "error": null,
                                    "processing_seconds": 28.6,
                                    "cancel_requested": false
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Error response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            },
            "delete": {
                "operationId": "jobs-cancel",
                "summary": "Cancel a job",
                "description": "A waiting job becomes cancelled immediately (without a callback, the reservation is released). A running job gets a cancel request (cancel_requested: true), the worker stops within a few seconds and reports job.failed with error.code = cancelled. A finished job gives 409 conflict.",
                "tags": [
                    "jobs"
                ],
                "parameters": [
                    {
                        "name": "job_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "id": "01J8Z6Q4T0M3S1V7B2X9K5N4RD",
                                    "status": "cancelled",
                                    "error": null,
                                    "cancel_requested": false
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Error response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/media/uploads": {
            "post": {
                "operationId": "uploads-create",
                "summary": "Create a direct upload",
                "description": "For sources without a public URL: returns a presigned PUT URL into our storage. Upload the file there and then use it as input.upload_id. Valid for 24 hours, usable once. Per team at most eight direct uploads and 10 GB of declared size in total are open at the same time. An upload keeps counting after it was assigned to a job until the row is removed.",
                "tags": [
                    "jobs"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "id": "01J8Z6Q4T0M3S1V7B2X9K5N4UP",
                                    "upload_url": "https://…",
                                    "method": "PUT",
                                    "headers": {
                                        "Content-Type": "video/mp4",
                                        "Content-Length": "734003200"
                                    },
                                    "expires_at": "2026-09-29T10:00:00Z"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Error response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "filename": {
                                        "type": "string",
                                        "description": "File name, at most 255 characters"
                                    },
                                    "size": {
                                        "type": "integer",
                                        "description": "Size in bytes, required. The presigned PUT URL signs exactly this Content-Length; a larger body is rejected by the storage."
                                    },
                                    "content_type": {
                                        "type": "string",
                                        "description": "Content-Type that must be sent with the PUT"
                                    }
                                },
                                "required": [
                                    "size"
                                ]
                            },
                            "example": {
                                "filename": "kurs-01.mp4",
                                "size": 734003200,
                                "content_type": "video/mp4"
                            }
                        }
                    }
                }
            }
        },
        "/media/usage": {
            "get": {
                "operationId": "usage",
                "summary": "Get usage",
                "description": "Jobs, failures, compute time and input volume for the period (default: current month). Costs and balance are shown in the dashboard under Billing.",
                "tags": [
                    "jobs"
                ],
                "parameters": [
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "description": "Start date YYYY-MM-DD",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "description": "End date YYYY-MM-DD",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "from": "2026-09-01",
                                    "to": "2026-09-30",
                                    "jobs": 2143,
                                    "failed": 12,
                                    "processing_seconds": 61234.5,
                                    "input_bytes": 98765432100,
                                    "by_pipeline": {
                                        "ugc_video": 2051,
                                        "ugc_image": 92
                                    }
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Error response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/media/health": {
            "get": {
                "operationId": "health",
                "summary": "Status",
                "description": "No authentication. ok, degraded (maintenance or limited image processing) or down, plus the queue length.",
                "tags": [
                    "jobs"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "status": "ok",
                                    "queue": {
                                        "pending": 3,
                                        "processing": 4
                                    },
                                    "version": "1.0.0"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Error response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/media/assets/{key}": {
            "put": {
                "operationId": "assets-put",
                "summary": "Upload a watermark",
                "description": "Body as raw PNG (Content-Type: image/png) or multipart with the field file. Answers 201 for a new key, 200 for a new version.",
                "tags": [
                    "assets"
                ],
                "parameters": [
                    {
                        "name": "key",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "key": "brand_white",
                                    "sha256": "c0ffee…",
                                    "width": 800,
                                    "height": 200,
                                    "size": 18234,
                                    "updated_at": "2026-09-28T10:00:00Z"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Error response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "file": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "PNG with alpha channel, at most 2 MB"
                                    }
                                },
                                "required": [
                                    "file"
                                ]
                            }
                        }
                    }
                }
            },
            "post": {
                "operationId": "assets-post",
                "summary": "Upload a watermark (POST)",
                "description": "Same as PUT, for clients that can only send multipart with POST.",
                "tags": [
                    "assets"
                ],
                "parameters": [
                    {
                        "name": "key",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "key": "brand_white",
                                    "sha256": "c0ffee…",
                                    "width": 800,
                                    "height": 200,
                                    "size": 18234,
                                    "updated_at": "2026-09-28T10:00:00Z"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Error response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "file": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "PNG with alpha channel, at most 2 MB"
                                    }
                                },
                                "required": [
                                    "file"
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/media/assets": {
            "get": {
                "operationId": "assets-list",
                "summary": "List watermarks",
                "description": "All watermarks of your team with their current version.",
                "tags": [
                    "assets"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "data": [
                                        {
                                            "key": "brand_white",
                                            "sha256": "c0ffee…",
                                            "width": 800,
                                            "height": 200,
                                            "size": 18234,
                                            "updated_at": "2026-09-28T10:00:00Z"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Error response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/media/webhook-endpoints": {
            "get": {
                "operationId": "webhook-endpoints-list",
                "summary": "List endpoints",
                "description": "All endpoints of your team, without the secret.",
                "tags": [
                    "callbacks"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "data": [
                                        {
                                            "id": "01J8Z6Q4T0M3S1V7B2X9K5N4WH",
                                            "url": "https://example.com/hooks/media",
                                            "description": null,
                                            "events": [
                                                "job.finished",
                                                "job.failed"
                                            ],
                                            "is_default": true,
                                            "active": true,
                                            "previous_secret_expires_at": null,
                                            "created_at": "2026-09-28T10:00:00Z"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Error response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "operationId": "webhook-endpoints-create",
                "summary": "Create an endpoint",
                "description": "Creates an endpoint and returns the secret once in the field secret. is_default: true takes the marker away from another endpoint.",
                "tags": [
                    "callbacks"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "id": "01J8Z6Q4T0M3S1V7B2X9K5N4WH",
                                    "url": "https://example.com/hooks/media",
                                    "events": [
                                        "job.finished",
                                        "job.failed"
                                    ],
                                    "is_default": true,
                                    "active": true,
                                    "secret": "whsec_BEISPIEL00000000000000000000000"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Error response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "url": {
                                        "type": "string",
                                        "description": "Public https URL"
                                    },
                                    "events": {
                                        "type": "array",
                                        "items": [],
                                        "description": "job.finished and/or job.failed (default: both)"
                                    },
                                    "description": {
                                        "type": "string",
                                        "description": "At most 191 characters"
                                    },
                                    "is_default": {
                                        "type": "boolean",
                                        "description": "Also signs free callback.url"
                                    }
                                },
                                "required": [
                                    "url"
                                ]
                            },
                            "example": {
                                "url": "https://example.com/hooks/media",
                                "events": [
                                    "job.finished",
                                    "job.failed"
                                ],
                                "is_default": true
                            }
                        }
                    }
                }
            }
        },
        "/media/webhook-endpoints/{endpoint_id}/rotate-secret": {
            "post": {
                "operationId": "webhook-endpoints-rotate",
                "summary": "Rotate the secret",
                "description": "Creates a new secret and returns it once. The old one keeps signing for 24 hours (previous_secret_expires_at).",
                "tags": [
                    "callbacks"
                ],
                "parameters": [
                    {
                        "name": "endpoint_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "id": "01J8Z6Q4T0M3S1V7B2X9K5N4WH",
                                    "previous_secret_expires_at": "2026-09-29T10:00:00Z",
                                    "secret": "whsec_…"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Error response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/media/webhook-endpoints/{endpoint_id}": {
            "delete": {
                "operationId": "webhook-endpoints-delete",
                "summary": "Delete an endpoint",
                "description": "Deletes the endpoint. Open deliveries to it are given up.",
                "tags": [
                    "callbacks"
                ],
                "parameters": [
                    {
                        "name": "endpoint_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "deleted": true,
                                    "id": "01J8Z6Q4T0M3S1V7B2X9K5N4WH"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Error response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "FlowData key as Authorization: Bearer fd_…"
            }
        },
        "schemas": {
            "Error": {
                "type": "object",
                "required": [
                    "error"
                ],
                "properties": {
                    "error": {
                        "type": "object",
                        "properties": {
                            "code": {
                                "type": "string"
                            },
                            "message": {
                                "type": "string"
                            },
                            "type": {
                                "type": "string"
                            },
                            "details": {
                                "type": "object"
                            }
                        }
                    }
                }
            }
        }
    }
}