Save Marketing Post Overlays (v1)

Method & Path

PUT /api/v1/workspace/:workspaceId/ai/usages/:usageId/overlays

Description

Save overlay configurations for a marketing post generation usage. This allows you to save text, badge, and image overlays that were configured in the frontend.

Authentication

Required: Workspace authentication. User must be authenticated as Workspace Owner or Staff with workspace permissions.

Headers

Authorization: Bearer <workspace_token>
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace identifier
usageId	string	Yes	AI tool usage identifier

Request Body

{
  "overlays": [
    {
      "id": "overlay-1",
      "type": "text",
      "text": "New Product",
      "visible": true,
      "style": {
        "fontFamily": "Arial",
        "fontWeight": 700,
        "fontSize": 24,
        "color": "#000000",
        "align": "center",
        "direction": "ltr"
      },
      "layout": {
        "x": 100,
        "y": 50,
        "w": 200,
        "h": 30
      }
    }
  ]
}

Request Body Schema

Field	Type	Required	Description
overlays	array	Yes	Array of overlay objects
overlays[].id	string	Yes	Overlay identifier
overlays[].type	string	Yes	Overlay type (text, badge, image)
overlays[].text	string	No	Text content (for text/badge overlays)
overlays[].imageUrl	string	No	Image URL (for image overlays)
overlays[].visible	boolean	No	Whether overlay is visible
overlays[].style	object	Yes	Overlay style configuration
overlays[].layout	object	Yes	Overlay layout/position configuration

Response 200 OK

{
  "success": true
}

Common Errors

400 Bad Request: Invalid request body or overlay configuration

401 Unauthorized: Missing or invalid authentication token

404 Not Found: Workspace or usage not found

422 Unprocessable Entity: Validation error

500 Internal Server Error: Server error occurred while processing the request

Notes

• Overlays are saved in the responseData.overlaysSaved field of the usage
• This endpoint is typically called after user configures overlays in the frontend
• Overlay configurations are used for generating final marketing post images