Your overlays
Create overlays, update them safely, and fork predefined ones into your own.
Pro and Ultimate only
Creating, updating and forking overlays needs the Pro or Ultimate plan. On Free these endpoints return 403 plan_required.
Create an overlay
/api/v1/overlaysinventory:writeBody
Name
Type
curl -s -X POST "$FORGECAST_URL/api/v1/overlays" \
-H "Authorization: Bearer $FORGECAST_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "My starting scene",
"document": {
"schema": 1,
"canvas": { "width": 1920, "height": 1080 },
"layers": [
{
"type": "text",
"id": "title",
"name": "Title",
"frame": { "x": 200, "y": 400, "w": 1520, "h": 200 },
"props": {
"text": "Starting soon",
"fontFamily": "Inter",
"fontSize": 120,
"fill": { "kind": "solid", "color": "#FFFFFF" }
}
}
]
}
}'Errors: 403 plan_required, 403 limit_reached, 400 validation_error (the document didn't pass the checks), 413 payload_too_large.
Update an overlay
Change the name and/or document of one of your overlays. On success its rev goes up by one.
/api/v1/overlays/:overlayIdinventory:writeBody
Name
Type
curl -s -X PUT "$FORGECAST_URL/api/v1/overlays/4b21..." \
-H "Authorization: Bearer $FORGECAST_KEY" \
-H "Content-Type: application/json" \
-d '{ "baseRev": 3, "name": "Renamed", "document": { "schema": 1, "canvas": { "width": 1920, "height": 1080 }, "layers": [] } }'Nothing is ever overwritten by accident. If someone saved in between (the desktop app on another PC, say) you get 409 conflict with details.currentRev. Fetch the item again, re-apply your change, and retry.
Fork a predefined overlay
Copy a predefined overlay into your own editable overlays. You can fork any overlay your plan can add.
/api/v1/overlays/forkinventory:writeBody
Name
Type
curl -s -X POST "$FORGECAST_URL/api/v1/overlays/fork" \
-H "Authorization: Bearer $FORGECAST_KEY" \
-H "Content-Type: application/json" \
-d '{ "slug": "midnight-forest", "name": "My remix" }'