SuggestionsEnvelope

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cueframe-ai/json-schema/cueframe-ai-suggestions-envelope-schema.json",
  "title": "SuggestionsEnvelope",
  "description": "GET /media/:id/suggestions envelope.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cueframe-ai-clips-api-openapi.yml#/components/schemas/SuggestionsEnvelope",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "idle",
        "generating",
        "completed",
        "failed"
      ]
    },
    "createdAt": {
      "type": [
        "string",
        "null"
      ]
    },
    "analyzedAt": {
      "type": [
        "string",
        "null"
      ]
    },
    "jobId": {
      "type": [
        "string",
        "null"
      ]
    },
    "topics": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "suggestions": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Suggestion"
      }
    },
    "pagination": {
      "$ref": "#/$defs/PaginationMeta"
    }
  },
  "required": [
    "status",
    "createdAt",
    "analyzedAt",
    "jobId",
    "topics",
    "suggestions",
    "pagination"
  ],
  "additionalProperties": false,
  "$defs": {
    "PaginationMeta": {
      "type": "object",
      "properties": {
        "hasMore": {
          "type": "boolean"
        },
        "nextCursor": {
          "type": [
            "string",
            "null"
          ]
        },
        "prevCursor": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "hasMore",
        "nextCursor",
        "prevCursor"
      ],
      "additionalProperties": false,
      "description": "Cursor pagination metadata."
    },
    "Suggestion": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "briefId": {
          "type": [
            "string",
            "null"
          ]
        },
        "rank": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "trim": {
          "type": "object",
          "properties": {
            "start": {
              "type": "number"
            },
            "end": {
              "type": "number"
            }
          },
          "required": [
            "start",
            "end"
          ],
          "additionalProperties": false
        },
        "score": {
          "type": "number"
        },
        "title": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        },
        "topic": {
          "type": "string"
        },
        "hook": {
          "type": "string"
        },
        "platforms": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "format": {
          "type": "string"
        },
        "caption": {
          "type": "string"
        },
        "hashtags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "textOverlays": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "editingNotes": {
          "type": "string"
        },
        "motionStyle": {
          "type": "object",
          "properties": {
            "textAnimation": {
              "type": "string"
            },
            "transitions": {
              "type": "string"
            },
            "colorMood": {
              "type": "string"
            },
            "captionStyle": {
              "type": "string"
            }
          },
          "required": [
            "textAnimation",
            "transitions",
            "colorMood",
            "captionStyle"
          ],
          "additionalProperties": false
        },
        "visualTreatment": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "time": {
                "type": [
                  "number",
                  "string"
                ]
              },
              "visual": {
                "type": "string"
              }
            },
            "required": [
              "time",
              "visual"
            ],
            "additionalProperties": false
          }
        },
        "brollSuggestions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "moment": {
                "type": "string"
              },
              "searchTerms": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "rationale": {
                "type": "string"
              }
            },
            "required": [
              "moment",
              "searchTerms",
              "rationale"
            ],
            "additionalProperties": false
          }
        },
        "thumbnailConcept": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "briefId",
        "rank",
        "trim",
        "score",
        "title",
        "reason",
        "topic",
        "hook",
        "platforms",
        "format",
        "caption",
        "hashtags",
        "textOverlays",
        "editingNotes",
        "motionStyle",
        "visualTreatment",
        "brollSuggestions",
        "thumbnailConcept"
      ],
      "additionalProperties": false,
      "description": "Single ranked clip suggestion."
    }
  }
}