JobStatusEnvelope

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/everpop-app/json-schema/everpop-app-job-status-envelope-schema.json",
  "title": "JobStatusEnvelope",
  "x-generated": "2026-11-07",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/everpop-app-openapi.json#/components/schemas/JobStatusEnvelope",
  "type": "object",
  "properties": {
    "ok": {
      "const": true
    },
    "data": {
      "type": "object",
      "properties": {
        "jobId": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "PENDING",
            "PROCESSING",
            "COMPLETED",
            "FAILED",
            "CANCELED"
          ],
          "description": "Stop polling on any status other than PENDING or PROCESSING."
        },
        "error": {
          "type": [
            "string",
            "null"
          ],
          "description": "Customer-safe failure detail when the job did not complete."
        },
        "clipCountApplied": {
          "type": [
            "integer",
            "null"
          ],
          "description": "The clip count the job runs with after the plan's per-video cap (1 for a Summary or Punch)."
        },
        "clips": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ClipItem"
          }
        }
      },
      "required": [
        "jobId",
        "status",
        "error",
        "clipCountApplied",
        "clips"
      ]
    }
  },
  "required": [
    "ok",
    "data"
  ],
  "$defs": {
    "ClipItem": {
      "type": "object",
      "properties": {
        "clipId": {
          "type": "string",
          "description": "The id POST /api/v1/publish takes (equal to id)."
        },
        "id": {
          "type": "string"
        },
        "title": {
          "type": [
            "string",
            "null"
          ]
        },
        "clipUrl": {
          "type": [
            "string",
            "null"
          ],
          "description": "Publicly fetchable MP4 once rendered."
        },
        "thumbnailUrl": {
          "type": [
            "string",
            "null"
          ]
        },
        "durationSeconds": {
          "type": [
            "integer",
            "null"
          ]
        },
        "status": {
          "type": "string"
        },
        "review": {
          "$ref": "#/$defs/ClipReview"
        }
      },
      "required": [
        "clipId",
        "id",
        "title",
        "clipUrl",
        "thumbnailUrl",
        "durationSeconds",
        "status",
        "review"
      ]
    },
    "ClipReview": {
      "type": "object",
      "description": "What to tell the user before asking them to confirm a publish. Clips with quality-check warnings can still be published by the user's explicit choice; mention the warnings.",
      "properties": {
        "qcWarnings": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/QcWarning"
          },
          "description": "Owner-facing quality-check warnings; empty when the clip passed."
        },
        "sourceStartSeconds": {
          "type": [
            "number",
            "null"
          ],
          "description": "Where the clip starts in the source video, in seconds (null on older clips)."
        },
        "sourceEndSeconds": {
          "type": [
            "number",
            "null"
          ],
          "description": "Where the clip ends in the source video, in seconds (null on older clips)."
        },
        "archetype": {
          "type": [
            "string",
            "null"
          ],
          "description": "The editorial cut, e.g. top_moments, summary, punch."
        },
        "captions": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "NONE",
            "PENDING",
            "BURNED_IN",
            "FAILED",
            null
          ],
          "description": "Caption state."
        },
        "hook": {
          "type": [
            "string",
            "null"
          ],
          "description": "The words spoken in the clip's opening seconds, when recorded."
        },
        "width": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Rendered width in pixels, measured from the file (null when not measured)."
        },
        "height": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Rendered height in pixels, measured from the file (null when not measured)."
        },
        "heldForReview": {
          "type": "boolean",
          "description": "true when an earlier publish attempt left the clip held for content review (publishing answers 403 content_review until it is cleared)."
        }
      },
      "required": [
        "qcWarnings",
        "sourceStartSeconds",
        "sourceEndSeconds",
        "archetype",
        "captions",
        "hook",
        "width",
        "height",
        "heldForReview"
      ]
    },
    "QcWarning": {
      "type": "object",
      "properties": {
        "flag": {
          "type": "string",
          "description": "Stable machine key (e.g. profanity, dead_zone); _other for a flag without specific copy."
        },
        "label": {
          "type": "string"
        },
        "detail": {
          "type": "string"
        }
      },
      "required": [
        "flag",
        "label",
        "detail"
      ]
    }
  }
}