API reference / Promo videos

Apply a video candidate

POST/api/v1/promovideo/apply-candidate

Authorization

Send your API key or MCP OAuth token in the Authorization: Bearer header. Active or trialing Unlimited is required.

Required permission designs:write

Every mutation requires JSON and an Idempotency-Key. Reuse the same key and exact input when retrying.

Parameters

Idempotency-Keyheaderrequired

string

Persist this key for retries. Reusing it with changed input returns 409. Receipts are retained for at least 24 hours.

min length: 8 · max length: 128

Request body

application/json

projectIdbodyrequired

string · uuid

configbodyrequired

object

labelbodyoptional

string

min length: 1 · max length: 120

replaceVariantIdbodyoptional

string · uuid

View complete request schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "config": {
      "type": "object",
      "properties": {
        "scenes": {
          "maxItems": 100,
          "type": "array",
          "items": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "duration": {
                    "anyOf": [
                      {
                        "type": "number",
                        "exclusiveMinimum": 0,
                        "maximum": 3600
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "hidden": {
                    "type": "boolean"
                  },
                  "type": {
                    "type": "string",
                    "const": "hook"
                  },
                  "content": {
                    "type": "object",
                    "properties": {
                      "appName": {
                        "anyOf": [
                          {
                            "type": "string",
                            "maxLength": 20000
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "tagline": {
                        "anyOf": [
                          {
                            "type": "string",
                            "maxLength": 20000
                          },
                          {
                            "type": "null"
                          }
                        ]
                      }
                    },
                    "additionalProperties": {}
                  }
                },
                "required": [
                  "type",
                  "content"
                ],
                "additionalProperties": {}
              },
              {
                "type": "object",
                "properties": {
                  "duration": {
                    "anyOf": [
                      {
                        "type": "number",
                        "exclusiveMinimum": 0,
                        "maximum": 3600
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "hidden": {
                    "type": "boolean"
                  },
                  "type": {
                    "type": "string",
                    "const": "feature"
                  },
                  "content": {
                    "type": "object",
                    "properties": {
                      "screenshotIndex": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 99
                      },
                      "title": {
                        "type": "string",
                        "maxLength": 20000
                      },
                      "subtitle": {
                        "anyOf": [
                          {
                            "type": "string",
                            "maxLength": 20000
                          },
                          {
                            "type": "null"
                          }
                        ]
                      }
                    },
                    "required": [
                      "screenshotIndex",
                      "title"
                    ],
                    "additionalProperties": {}
                  }
                },
                "required": [
                  "type",
                  "content"
                ],
                "additionalProperties": {}
              },
              {
                "type": "object",
                "properties": {
                  "duration": {
                    "anyOf": [
                      {
                        "type": "number",
                        "exclusiveMinimum": 0,
                        "maximum": 3600
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "hidden": {
                    "type": "boolean"
                  },
                  "type": {
                    "type": "string",
                    "const": "text-only"
                  },
                  "content": {
                    "type": "object",
                    "properties": {
                      "headline": {
                        "type": "string",
                        "maxLength": 20000
                      },
                      "subheadline": {
                        "anyOf": [
                          {
                            "type": "string",
                            "maxLength": 20000
                          },
                          {
                            "type": "null"
                          }
                        ]
                      }
                    },
                    "required": [
                      "headline"
                    ],
                    "additionalProperties": {}
                  }
                },
                "required": [
                  "type",
                  "content"
                ],
                "additionalProperties": {}
              },
              {
                "type": "object",
                "properties": {
                  "duration": {
                    "anyOf": [
                      {
                        "type": "number",
                        "exclusiveMinimum": 0,
                        "maximum": 3600
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "hidden": {
                    "type": "boolean"
                  },
                  "type": {
                    "type": "string",
                    "const": "closeup"
                  },
                  "content": {
                    "type": "object",
                    "properties": {
                      "screenshotIndex": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 99
                      },
                      "caption": {
                        "anyOf": [
                          {
                            "type": "string",
                            "maxLength": 20000
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "focusRegion": {
                        "anyOf": [
                          {
                            "type": "object",
                            "properties": {
                              "x": {
                                "type": "number"
                              },
                              "y": {
                                "type": "number"
                              },
                              "width": {
                                "type": "number",
                                "exclusiveMinimum": 0
                              },
                              "height": {
                                "type": "number",
                                "exclusiveMinimum": 0
                              }
                            },
                            "required": [
                              "x",
                              "y",
                              "width",
                              "height"
                            ]
                          },
                          {
                            "type": "null"
                          }
                        ]
                      }
                    },
                    "required": [
                      "screenshotIndex"
                    ],
                    "additionalProperties": {}
                  }
                },
                "required": [
                  "type",
                  "content"
                ],
                "additionalProperties": {}
              },
              {
                "type": "object",
                "properties": {
                  "duration": {
                    "anyOf": [
                      {
                        "type": "number",
                        "exclusiveMinimum": 0,
                        "maximum": 3600
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "hidden": {
                    "type": "boolean"
                  },
                  "type": {
                    "type": "string",
                    "const": "multi-phone"
                  },
                  "content": {
                    "type": "object",
                    "properties": {
                      "screenshotIndexes": {
                        "minItems": 1,
                        "maxItems": 6,
                        "type": "array",
                        "items": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 99
                        }
                      },
                      "title": {
                        "anyOf": [
                          {
                            "type": "string",
                            "maxLength": 20000
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "layout": {
                        "type": "string",
                        "enum": [
                          "cascade",
                          "fan",
                          "side-by-side",
                          "custom"
                        ]
                      }
                    },
                    "required": [
                      "screenshotIndexes",
                      "layout"
                    ],
                    "additionalProperties": {}
                  }
                },
                "required": [
                  "type",
                  "content"
                ],
                "additionalProperties": {}
              },
              {
                "type": "object",
                "properties": {
                  "duration": {
                    "anyOf": [
                      {
                        "type": "number",
                        "exclusiveMinimum": 0,
                        "maximum": 3600
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "hidden": {
                    "type": "boolean"
                  },
                  "type": {
                    "type": "string",
                    "const": "cta"
                  },
                  "content": {
                    "type": "object",
                    "properties": {
                      "appName": {
                        "anyOf": [
                          {
                            "type": "string",
                            "maxLength": 20000
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "downloadText": {
                        "anyOf": [
                          {
                            "type": "string",
                            "maxLength": 20000
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "badge": {
                        "anyOf": [
                          {
                            "type": "string",
                            "enum": [
                              "appStore",
                              "googlePlay",
                              "both",
                              "none"
                            ]
                          },
                          {
                            "type": "null"
                          }
                        ]
                      }
                    },
                    "additionalProperties": {}
                  }
                },
                "required": [
                  "type",
                  "content"
                ],
                "additionalProperties": {}
              }
            ]
          }
        },
        "theme": {
          "type": "object",
          "properties": {
            "colors": {
              "type": "object",
              "propertyNames": {
                "type": "string"
              },
              "additionalProperties": {
                "type": "string"
              }
            },
            "typography": {
              "type": "object",
              "properties": {
                "fontFamily": {
                  "type": "string"
                },
                "titleSize": {
                  "type": "number",
                  "exclusiveMinimum": 0
                },
                "subtitleSize": {
                  "type": "number",
                  "exclusiveMinimum": 0
                }
              },
              "additionalProperties": {}
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "scenes"
      ],
      "additionalProperties": {}
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "replaceVariantId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "required": [
    "projectId",
    "config"
  ],
  "additionalProperties": false
}

Request example

Set ALF_API_URL to https://dashboard.applaunchflow.com/api/v1 and ALF_API_KEY to your key. Replace sample IDs with your project’s values. Use a new ALF_REQUEST_ID for each new operation.

cURL

curl --request POST \
  --url "$ALF_API_URL/promovideo/apply-candidate" \
  --header "Authorization: Bearer $ALF_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $ALF_REQUEST_ID" \
  --data '{
  "projectId": "11111111-1111-4111-8111-111111111111",
  "config": {
    "scenes": [
      {
        "type": "hook",
        "content": {}
      }
    ]
  }
}'

This example shows the request structure. Some editor operations require additional query parameters that are not yet described in OpenAPI.

Response

Successful JSON responses wrap the result in data, with a request ID in meta.requestId.

configdatarequired

object

durationInFramesdatarequired

integer

minimum: -9007199254740991 · maximum: 9007199254740991

fontFamilydatarequired

string

projectIddatarequired

string · uuid

variantIddatarequired

string · uuid

View response schema

{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "config": {
          "type": "object",
          "properties": {
            "scenes": {
              "maxItems": 100,
              "type": "array",
              "items": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "duration": {
                        "anyOf": [
                          {
                            "type": "number",
                            "exclusiveMinimum": 0,
                            "maximum": 3600
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "hidden": {
                        "type": "boolean"
                      },
                      "type": {
                        "type": "string",
                        "const": "hook"
                      },
                      "content": {
                        "type": "object",
                        "properties": {
                          "appName": {
                            "anyOf": [
                              {
                                "type": "string",
                                "maxLength": 20000
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "tagline": {
                            "anyOf": [
                              {
                                "type": "string",
                                "maxLength": 20000
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "additionalProperties": {}
                      }
                    },
                    "required": [
                      "type",
                      "content"
                    ],
                    "additionalProperties": {}
                  },
                  {
                    "type": "object",
                    "properties": {
                      "duration": {
                        "anyOf": [
                          {
                            "type": "number",
                            "exclusiveMinimum": 0,
                            "maximum": 3600
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "hidden": {
                        "type": "boolean"
                      },
                      "type": {
                        "type": "string",
                        "const": "feature"
                      },
                      "content": {
                        "type": "object",
                        "properties": {
                          "screenshotIndex": {
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 99
                          },
                          "title": {
                            "type": "string",
                            "maxLength": 20000
                          },
                          "subtitle": {
                            "anyOf": [
                              {
                                "type": "string",
                                "maxLength": 20000
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "screenshotIndex",
                          "title"
                        ],
                        "additionalProperties": {}
                      }
                    },
                    "required": [
                      "type",
                      "content"
                    ],
                    "additionalProperties": {}
                  },
                  {
                    "type": "object",
                    "properties": {
                      "duration": {
                        "anyOf": [
                          {
                            "type": "number",
                            "exclusiveMinimum": 0,
                            "maximum": 3600
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "hidden": {
                        "type": "boolean"
                      },
                      "type": {
                        "type": "string",
                        "const": "text-only"
                      },
                      "content": {
                        "type": "object",
                        "properties": {
                          "headline": {
                            "type": "string",
                            "maxLength": 20000
                          },
                          "subheadline": {
                            "anyOf": [
                              {
                                "type": "string",
                                "maxLength": 20000
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "headline"
                        ],
                        "additionalProperties": {}
                      }
                    },
                    "required": [
                      "type",
                      "content"
                    ],
                    "additionalProperties": {}
                  },
                  {
                    "type": "object",
                    "properties": {
                      "duration": {
                        "anyOf": [
                          {
                            "type": "number",
                            "exclusiveMinimum": 0,
                            "maximum": 3600
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "hidden": {
                        "type": "boolean"
                      },
                      "type": {
                        "type": "string",
                        "const": "closeup"
                      },
                      "content": {
                        "type": "object",
                        "properties": {
                          "screenshotIndex": {
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 99
                          },
                          "caption": {
                            "anyOf": [
                              {
                                "type": "string",
                                "maxLength": 20000
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "focusRegion": {
                            "anyOf": [
                              {
                                "type": "object",
                                "properties": {
                                  "x": {
                                    "type": "number"
                                  },
                                  "y": {
                                    "type": "number"
                                  },
                                  "width": {
                                    "type": "number",
                                    "exclusiveMinimum": 0
                                  },
                                  "height": {
                                    "type": "number",
                                    "exclusiveMinimum": 0
                                  }
                                },
                                "required": [
                                  "x",
                                  "y",
                                  "width",
                                  "height"
                                ]
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "screenshotIndex"
                        ],
                        "additionalProperties": {}
                      }
                    },
                    "required": [
                      "type",
                      "content"
                    ],
                    "additionalProperties": {}
                  },
                  {
                    "type": "object",
                    "properties": {
                      "duration": {
                        "anyOf": [
                          {
                            "type": "number",
                            "exclusiveMinimum": 0,
                            "maximum": 3600
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "hidden": {
                        "type": "boolean"
                      },
                      "type": {
                        "type": "string",
                        "const": "multi-phone"
                      },
                      "content": {
                        "type": "object",
                        "properties": {
                          "screenshotIndexes": {
                            "minItems": 1,
                            "maxItems": 6,
                            "type": "array",
                            "items": {
                              "type": "integer",
                              "minimum": 0,
                              "maximum": 99
                            }
                          },
                          "title": {
                            "anyOf": [
                              {
                                "type": "string",
                                "maxLength": 20000
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "layout": {
                            "type": "string",
                            "enum": [
                              "cascade",
                              "fan",
                              "side-by-side",
                              "custom"
                            ]
                          }
                        },
                        "required": [
                          "screenshotIndexes",
                          "layout"
                        ],
                        "additionalProperties": {}
                      }
                    },
                    "required": [
                      "type",
                      "content"
                    ],
                    "additionalProperties": {}
                  },
                  {
                    "type": "object",
                    "properties": {
                      "duration": {
                        "anyOf": [
                          {
                            "type": "number",
                            "exclusiveMinimum": 0,
                            "maximum": 3600
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "hidden": {
                        "type": "boolean"
                      },
                      "type": {
                        "type": "string",
                        "const": "cta"
                      },
                      "content": {
                        "type": "object",
                        "properties": {
                          "appName": {
                            "anyOf": [
                              {
                                "type": "string",
                                "maxLength": 20000
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "downloadText": {
                            "anyOf": [
                              {
                                "type": "string",
                                "maxLength": 20000
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "badge": {
                            "anyOf": [
                              {
                                "type": "string",
                                "enum": [
                                  "appStore",
                                  "googlePlay",
                                  "both",
                                  "none"
                                ]
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "additionalProperties": {}
                      }
                    },
                    "required": [
                      "type",
                      "content"
                    ],
                    "additionalProperties": {}
                  }
                ]
              }
            },
            "theme": {
              "type": "object",
              "properties": {
                "colors": {
                  "type": "object",
                  "propertyNames": {
                    "type": "string"
                  },
                  "additionalProperties": {
                    "type": "string"
                  }
                },
                "typography": {
                  "type": "object",
                  "properties": {
                    "fontFamily": {
                      "type": "string"
                    },
                    "titleSize": {
                      "type": "number",
                      "exclusiveMinimum": 0
                    },
                    "subtitleSize": {
                      "type": "number",
                      "exclusiveMinimum": 0
                    }
                  },
                  "additionalProperties": {}
                }
              },
              "additionalProperties": {}
            }
          },
          "required": [
            "scenes"
          ],
          "additionalProperties": {}
        },
        "durationInFrames": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        "fontFamily": {
          "type": "string"
        },
        "projectId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "variantId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        }
      },
      "required": [
        "config",
        "durationInFrames",
        "fontFamily",
        "projectId",
        "variantId"
      ],
      "additionalProperties": {}
    },
    "meta": {
      "type": "object",
      "required": [
        "requestId"
      ],
      "properties": {
        "requestId": {
          "type": "string",
          "format": "uuid"
        }
      }
    }
  }
}

Errors & retries

Errors use application/problem+json. Check the stable code and keep requestId when contacting support. Respect Retry-After on 429 responses.

See error handling and idempotency →