{"openapi":"3.0.0","info":{"title":"Layouts API","description":"Manages layouts within Dotdigital Personalization, which define the structural templates used to render personalised content. Layouts control how smartblocks and slot content are assembled and displayed to end users. Operations include listing, creating, retrieving, updating, and deleting layouts.","version":"1.0.1"},"servers":[{"url":"https://{region}-api-freshrelevance.dotdigital.com/api","variables":{"region":{"description":"The region id your account belongs to","enum":["r1","r2","r3"],"default":"r1"}}}],"security":[{"apiTokenAuth":[]}],"paths":{"/{website_id}/layouts/":{"get":{"tags":["Manage layouts"],"summary":"List layouts","description":"Retrieves layouts using the specified filters.","operationId":"getListLayouts","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"name":"limit","in":"query","description":"Get this number of records to return in results array (pagination).","schema":{"minimum":1,"type":"integer","default":25},"example":50},{"name":"page","in":"query","description":"Which page of results you wish to return; First page is indexed as 1.","schema":{"type":"integer","default":1},"example":1},{"name":"include_deleted","in":"query","description":"Include deleted layouts in the results.","required":false,"schema":{"type":"boolean","default":false}},{"name":"include_live_flag","in":"query","description":"Include `is_live` field in the results.","required":false,"schema":{"type":"boolean","default":false}},{"name":"include_html","in":"query","description":"Include `html` field in the results.","required":false,"schema":{"type":"boolean","default":true}},{"name":"include_system","in":"query","description":"Include standard system layouts in the results.","required":false,"schema":{"type":"boolean","default":false}},{"name":"only_templates","in":"query","description":"Include only template layouts in the results.","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"The page of layouts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}},"post":{"tags":["Manage layouts"],"summary":"Create layout","description":"Creates a new layout.","operationId":"postCreateLayout","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/website_id_layouts_body"}}}},"responses":{"200":{"description":"The created layout slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/callSlugResponse"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}}},"/{website_id}/layouts/{slug}/":{"get":{"tags":["Manage layouts"],"summary":"Get layout","description":"Retrieves a layouts details.","operationId":"getLayout","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"name":"slug","in":"path","description":"The unique id / slug to update.","required":true,"schema":{"type":"string"},"example":"my-slug"},{"name":"include_deleted","in":"query","description":"Include deleted layouts in the results.","required":false,"schema":{"type":"boolean","default":false}},{"name":"include_live_flag","in":"query","description":"Include `is_live` field in the results.","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"The layout details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/layoutDetails"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}},"post":{"tags":["Manage layouts"],"summary":"Update layout","description":"Updates a layout.","operationId":"postUpdateLayout","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"name":"slug","in":"path","description":"The unique id / slug to update.","required":true,"schema":{"type":"string"},"example":"my-slug"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/layoutUpdate"}}}},"responses":{"200":{"description":"The created layout slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/callSlugResponse"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}},"delete":{"tags":["Manage layouts"],"summary":"Delete layout","description":"Deletes a layout.","operationId":"delLayout","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"name":"slug","in":"path","description":"The unique id / slug to update.","required":true,"schema":{"type":"string"},"example":"my-slug"}],"responses":{"200":{"description":"The deleted layout details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200_1"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}}},"/{website_id}/layouts/{slug}/clone/":{"post":{"tags":["Manage layouts"],"summary":"Clone layout","description":"Clones a layout.","operationId":"postCloneLayout","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"name":"slug","in":"path","description":"The unique id / slug to update.","required":true,"schema":{"type":"string"},"example":"my-slug"}],"responses":{"200":{"description":"The created layout slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/layoutDetails"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}}},"/{website_id}/layouts/{slugs}/bulk/":{"post":{"tags":["Bulk operations"],"summary":"Bulk update layout","description":"Updates multiple layouts with the same details.","operationId":"postBulkUpdateLayout","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"name":"slugs","in":"path","description":"Slot slug(s), comma delimited list of slugs","required":true,"style":"simple","schema":{"type":"array","items":{"maxLength":100,"minLength":1,"type":"string","example":"wddaq4t"}}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/slugs_bulk_body"}}}},"responses":{"200":{"description":"The created layout slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/callSlugResponse"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}},"delete":{"tags":["Bulk operations"],"summary":"Bulk delete layouts","description":"Deletes multiple layouts.","operationId":"delBulkLayout","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"name":"slugs","in":"path","description":"Slot slug(s), comma delimited list of slugs","required":true,"style":"simple","schema":{"type":"array","items":{"maxLength":100,"minLength":1,"type":"string","example":"wddaq4t"}}}],"responses":{"200":{"description":"The deleted layout details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/slugs_bulk_body"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}}}},"components":{"schemas":{"layoutBase":{"type":"object","properties":{"name":{"maxLength":256,"description":"The name of the layout.","example":"Standard Countdown"},"type":{"maxLength":10,"type":"string","description":"The type of layout.","example":"countdown","enum":["engage","recover","convert","countdown","twitter","pinterest","webcrop","custom","product","banner","coupon","popover","instagram","reviews"]},"template_style":{"type":"string","description":"The id of the template style applied.","nullable":true},"html":{"type":"string","description":"The layouts HTML markup.","format":"html","example":"<html><body>Hello World!</body></html>"},"content_tag":{"type":"array","description":"Any tags associated with the content.","nullable":true,"example":"null","items":{"type":"string","description":"Tag"}},"active":{"type":"boolean","description":"Whether the layout is active or not.","example":true},"placement":{"type":"array","description":"Where the layouts can be used.","items":{"type":"string","example":"email","enum":["web","email"]}},"thumbnail_url":{"type":"string","description":"The thumbnail URL for this layout.","format":"uri"},"is_template":{"type":"boolean","description":"Indicates whether the layout is a template.","example":true},"meta_data":{"type":"object","additionalProperties":true,"description":"Any additional meta data to store with the layout."},"merges":{"type":"string","description":"Merge information.","nullable":true}}},"layoutCreate":{"allOf":[{"$ref":"#/components/schemas/layoutBase"},{"required":["html","name","type"],"type":"object"}]},"layoutDetails":{"allOf":[{"$ref":"#/components/schemas/layoutBase"},{"required":["active","content_tag","dt","is_template","last_edited_by","name","placement","slug","template_style","template_type","thumbnail_url","type","version"],"type":"object","properties":{"slug":{"type":"string","description":"The unique identifier for the layout.","example":"ai1i583"},"dt":{"type":"string","description":"The date time when this layout was modified in UTC ISO-8601 format.","format":"date-time","example":"2024-10-28T18:15:27.176Z"},"version":{"minimum":1,"type":"integer","description":"The version number of the layout."},"last_edited_by":{"type":"string","description":"Username of who updated the Slot last.","nullable":true,"example":"joe.blogs"},"template_type":{"type":"string","description":"The type of template.","enum":["account","system"]},"is_live":{"type":"boolean","description":"Indicates whether the layout is in active use.","example":true},"meta_data":{"type":"object","additionalProperties":true,"description":"Any additional meta data to store with the layout."},"merges":{"type":"string","description":"Merge information.","nullable":true}}}]},"layoutUpdate":{"type":"object","properties":{"html":{"type":"string","description":"The layouts HTML markup.","format":"html","example":"<html><body>Hello World!</body></html>"},"active":{"type":"boolean","description":"Whether the layout is active or not.","example":true}},"description":"The new layout details."},"callSlugResponse":{"required":["ok","results","slug"],"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the call succeeded or not.","example":true,"enum":[true]},"slug":{"type":"string","description":"Unique identifier.","example":"my-new-item"},"results":{"minLength":1,"type":"array","description":"Updated layout details.","items":{"$ref":"#/components/schemas/layoutDetails"}}}},"PaginatedData":{"required":["count","links","page","total"],"type":"object","properties":{"page":{"minimum":1,"type":"integer","description":"The index for the page of data returned.","example":1},"count":{"minimum":0,"type":"integer","description":"Number of records in the page.","example":12},"total":{"minimum":0,"type":"integer","description":"Total number of records in the set.","example":12},"links":{"$ref":"#/components/schemas/PaginatedData_links"}},"description":"Data page and pagination links"},"inline_response_200":{"allOf":[{"$ref":"#/components/schemas/PaginatedData"},{"required":["results"],"type":"object","properties":{"results":{"type":"array","description":"The layout details.","items":{"$ref":"#/components/schemas/layoutDetails"}}},"description":"Results."}]},"website_id_layouts_body":{"allOf":[{"description":"The new layout details."},{"$ref":"#/components/schemas/layoutCreate"}]},"inline_response_200_1":{"required":["ok","results"],"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the call succeeded or not.","example":true,"enum":[true]},"results":{"maxLength":1,"minLength":1,"type":"array","description":"Deleted layout details.","items":{"$ref":"#/components/schemas/layoutDetails"}}}},"slugs_bulk_body":{"required":["errors","ok","results"],"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the call succeeded or not.","example":true,"enum":[true]},"errors":{"type":"array","description":"Error messages.","items":{"type":"string"},"default":[]},"results":{"minLength":1,"type":"array","description":"Updated layout details.","items":{"$ref":"#/components/schemas/layoutDetails"}}}},"PaginatedData_links":{"type":"object","properties":{"next":{"type":"string","description":"URL of the next page.","format":"url","nullable":true},"previous":{"type":"string","description":"URL of the previous page.","format":"url","nullable":true}},"description":"Page navigation links"}},"responses":{"ErrorResponse":{"description":"An error occurred","content":{"application/json":{"schema":{"required":["error","ok"],"type":"object","properties":{"ok":{"type":"boolean","description":"Indicates the call failed","enum":[false]},"error":{"oneOf":[{"type":"string","description":"The reason the call errored","example":"Validation error. No folder bd8eciompb7y, unable to delete"},{"type":"object","additionalProperties":{"minItems":1,"type":"array","items":{"type":"string","example":"This field may not be null."}},"description":"Fields with issues and their errors"}]}}}}}},"403Response":{"description":"Forbidden - Usually you are requesting data for a website you don't have access to."}},"parameters":{"WebsiteId":{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},"FormatJson":{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},"Limit":{"name":"limit","in":"query","description":"Get this number of records to return in results array (pagination).","schema":{"minimum":1,"type":"integer","default":25},"example":50},"Page":{"name":"page","in":"query","description":"Which page of results you wish to return; First page is indexed as 1.","schema":{"type":"integer","default":1},"example":1}},"securitySchemes":{"apiTokenAuth":{"type":"apiKey","name":"x-api-key","in":"header"}}},"x-samples-languages":["curl","csharp","java","javascript","node","python","php","ruby"]}