> For the complete documentation index, see [llms.txt](https://docs.thebrief.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thebrief.ai/public-api/rest-api/designs.md).

# Designs

## List designs&#x20;

List all designs (not templates) you have access to with the user assigned to the credentials.

This endpoint makes an HTTP GET request to retrieve a list of designs from the specified API endpoint.

### **Request**

* Method: GET
* Endpoint: `https://api.thebrief.ai/v1/designs`
* Query Parameters:
  * `keyword` (string, optional): The keyword to search for a design name
  * `projectId` (integer, optional): Return only designs from a specific project
  * `folderId` (integer, optional): Return only designs from a specific folder
  * `limit` (integer, optional): The maximum number of designs to be returned. (max 50)
  * `cursor`  (string, optional): A cursor for pagination.
  * `apiGenerated`  (boolean, optional): Return only designs generated by API (excluded without this true)
  * `exactSearch` (boolean, optional): If true, it will return only the designs with the name equal to keyword. (For ex. keyword = 'Design Name 1' will return only designs with the name 'Design Name 1')
  * `orderBy`  (enum, optional): option to order the response results by next fields:&#x20;

    ```typescript
    ID
    NAME
    CREATED_AT
    UPDATED_AT
    ```
  * `orderDirection` (enum, optional): option to order the response by direction:

    ```
    ASC
    DESC
    ```

### Response

Upon a successful execution with a status code of 200, the response will be in JSON format and will include a "response" object containing an array of "nodes" with "id" and "name" properties, as well as a "pageInfo" object with "hasNextPage" and "endCursor" properties.

Request example:

```
{
    "response": {
        "nodes": [
            {
                "id": "3pqqql",
                "name": "Untitled design",
                "projectId": 826801,
                "folderId": 65422,
                "apiGenerated": false,
                "thumbUrl": "https://creatopy-cdn-ed8ea45.s3.eu-central-1.amazonaws.com/resize/designs/ppxmex/small?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASCU4ALRBLWFY5GGB%2F20250411%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20250411T104109Z&X-Amz-Expires=43200&X-Amz-Signature=7c9bd2845cf13a6f78fb9617fc95518a7bf5cd04f5e83f7abd3a3ff61cbaf0bd&X-Amz-SignedHeaders=host"
            },
            {
                "id": "lwp7dy",
                "name": "Untitled design",
                "projectId": 826801,
                "folderId": 242422,
                "apiGenerated": false,
                "thumbUrl": "https://creatopy-cdn-ed8ea45.s3.eu-central-1.amazonaws.com/resize/designs/ppxmex/small?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASCU4ALRBLWFY5GGB%2F20250411%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20250411T104109Z&X-Amz-Expires=43200&X-Amz-Signature=7c9bd2845cf13a6f78fb9617fc95518a7bf5cd04f5e83f7abd3a3ff61cbaf0bd&X-Amz-SignedHeaders=host"
            },
            {
                "id": "m0rg1n",
                "name": "Car test",
                "projectId": 826801,
                "folderId": 155232,
                "apiGenerated": false,
                "thumbUrl": "https://creatopy-cdn-ed8ea45.s3.eu-central-1.amazonaws.com/resize/designs/ppxmex/small?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASCU4ALRBLWFY5GGB%2F20250411%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20250411T104109Z&X-Amz-Expires=43200&X-Amz-Signature=7c9bd2845cf13a6f78fb9617fc95518a7bf5cd04f5e83f7abd3a3ff61cbaf0bd&X-Amz-SignedHeaders=host"
            },
            ...
            {
                "id": "q8lx0r",
                "name": "Zapi temp 2 - long name here for testing",
                "projectId": 826801,
                "folderId": null,
                "apiGenerated": false,
                "thumbUrl": "https://creatopy-cdn-ed8ea45.s3.eu-central-1.amazonaws.com/resize/designs/ppxmex/small?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASCU4ALRBLWFY5GGB%2F20250411%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20250411T104109Z&X-Amz-Expires=43200&X-Amz-Signature=7c9bd2845cf13a6f78fb9617fc95518a7bf5cd04f5e83f7abd3a3ff61cbaf0bd&X-Amz-SignedHeaders=host"
            },
            {
                "id": "jdeglo",
                "name": "Zapi temp_300x250px_Fri Sep 01 2023 copy",
                "projectId": 826801,
                "folderId": null,
                "apiGenerated": false,
                "thumbUrl": "https://creatopy-cdn-ed8ea45.s3.eu-central-1.amazonaws.com/resize/designs/ppxmex/small?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASCU4ALRBLWFY5GGB%2F20250411%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20250411T104109Z&X-Amz-Expires=43200&X-Amz-Signature=7c9bd2845cf13a6f78fb9617fc95518a7bf5cd04f5e83f7abd3a3ff61cbaf0bd&X-Amz-SignedHeaders=host"
            },
            {
                "id": "mexkl7",
                "name": "Zapi temp_300x250px_Mon Sep 04 2023",
                "projectId": 826801,
                "folderId": null,
                "apiGenerated": true,
                "thumbUrl": "https://creatopy-cdn-ed8ea45.s3.eu-central-1.amazonaws.com/resize/designs/ppxmex/small?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASCU4ALRBLWFY5GGB%2F20250411%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20250411T104109Z&X-Amz-Expires=43200&X-Amz-Signature=7c9bd2845cf13a6f78fb9617fc95518a7bf5cd04f5e83f7abd3a3ff61cbaf0bd&X-Amz-SignedHeaders=host"
            },
            {
                "id": "ydk1lz",
                "name": "Zapi temp",
                "projectId": 826801,
                "folderId": null,
                "apiGenerated": false,
                "thumbUrl": "https://creatopy-cdn-ed8ea45.s3.eu-central-1.amazonaws.com/resize/designs/ppxmex/small?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASCU4ALRBLWFY5GGB%2F20250411%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20250411T104109Z&X-Amz-Expires=43200&X-Amz-Signature=7c9bd2845cf13a6f78fb9617fc95518a7bf5cd04f5e83f7abd3a3ff61cbaf0bd&X-Amz-SignedHeaders=host"
            },
        ],
        "pageInfo": {
            "hasNextPage": true,
            "endCursor": "eyJsaW1pdCI6NTAsImxhc3RJZCI6MzEzNDI0Mn0="
        }
    }
}
```

The thumbUrl is valid for 12 hours, after which it must be rerun the query to regenerate it.

## Create design from template

Create a new design starting from a template&#x20;

This endpoint makes an HTTP POST to create a new design, starting from a template and applying specific element changes

### **Request**

* Method: POST
* Endpoint: `https://api.thebrief.ai/v1/designs`
* Body:
  * `templateHash` (string, required): The hash of the creative.
  * `elementsChanges` (array, required):
    * `elementName` (string, required): The name of the element.
    * `changes` (array of objects, required):
      * `attribute` (string, required):  The attribute to be changed. (Available attributes are: "LABEL", "SOURCE", "CODE", "VISIBILITY", "FONTVARIANT", "TEXTMARKDOWN", "TEXTCOLOR", "BGCOLOR", "SVGCOLORS", "LINEHEIGHT", "LETTERSPACING", "TEXTHTML")
      * `value` (string, required): The new value for the attribute.
  * `generalChanges` (object, optional):&#x20;
    * `backgroundColor` (string, optional):  Any valid hexadecimal color code. The valid hexadecimal color code must satisfy the following conditions. It should start from the '#' symbol. It should be followed by the letters from a-f, A-F, and/or digits from 0-9. The length of the hexadecimal color code should be either 6 or 3, excluding the '#' symbol
  * `generalSettings` (object, optional):
    * `newDesignProjectId` (integer, optional): The ID of the project where the newly generated design will be saved.&#x20;
    * `newDesignFolderId` (integer, optional): The ID of the folder, where the newly generated design will be saved. (If not provided, the new design will be created at the root of the provided project)
    * `newDesignName` (string, optional): The name of the newly generated design.

Valid values for `elementChanges` are (depending on attribute):

* LABEL: any valid string
* SOURCE: any valid public media file link (also Google Drive and Dropbox shared links)
* CODE: valid embed code
* VISIBILITY: 'true' or 'false' (as string)
* FONTVARIANT: any existing font weight value from the result of the endpoint `templates/fontVariants` for ex: '300italic', '400', '700italic', etc.
* TEXTMARKDOWN: 4 markdowns could be added to text elements
  * Link - \[This is the text]\(This will be the link)
  * Italic text - text between one star - (\* will be transformed as italic text \*)
  * Bold text - text between two pairs of stars - (\*\* will be transformed as bold text \*\*)
  * Bold italic text - text between two groups of three stars - (\*\*\*  will be bold and italic text  \*\*\*)&#x20;
* TEXTCOLOR: valid hexadecimal color code (#FFF or #FFFFFF) - used with TEXT and BUTTON layers
* BGCOLOR: valid hexadecimal color code  (#FFF or #FFFFFF) - used for changing the background for BUTTON or SHAPE layers
* SVGCOLORS: valid hexadecimal color list ("#123456", "#FFFFFF", "#AAAAAA") - used for layers which has an SVG file as source&#x20;
* LINEHEIGHT - used with TEXT layers
* LETTERSPACING - used with TEXT and BUTTON layers
* FONTFAMILY - used with TEXT and BUTTON layers
* TEXTHTML - multiple valid html tags can be used with TEXT layers&#x20;
  * allowedTags: \['p', 'br', 'strong', 'b', 'em', 'i', 'u', 'a', 'ul', 'ol', 'li', 'span', 'div', 'sub', 'sup'],
* ALTTEXT - any valid string. Applies to Image, video, SVG, shape and button elements

### **Response**

The response to this request

{% code title="Response example" %}

```json
{
    "response": {
        "status": "success",
        "design": {
            "hash": "n17z178"
        }
    }
}
```

{% endcode %}

## Update design

Updates a specific design

This endpoint makes an HTTP PUT request to update a design by applying specific element changes.

### **Request**

* Method: PUT
* Endpoint: `https://api.thebrief.ai/v1/designs`
* Body:

  * `designHash` (string, required): The hash of the creative.
  * `elementsChanges` (array, required):
    * `elementName` (string, required): The name of the element.
    * `changes` (array of objects, required):
      * `attribute` (string, required):  The attribute to be changed. (Available attributes are: "LABEL", "SOURCE", "CODE", "VISIBILITY", "FONTVARIANT", "TEXTMARKDOWN", "TEXTCOLOR", "BGCOLOR", "SVGCOLORS", "LINEHEIGHT", "LETTERSPACING", "TEXTHTML")
      * `value` (string, required): The new value for the attribute.
  * `generalChanges` (object, optional):&#x20;
    * `backgroundColor` (string, optional):  Any valid hexadecimal color code. The valid hexadecimal color code must satisfy the following conditions. It should start from the '#' symbol. It should be followed by the letters from a-f, A-F, and/or digits from 0-9. The length of the hexadecimal color code should be either 6 or 3, excluding the '#' symbol

Valid values for `elementChanges` (depending on attribute):

* LABEL: any valid string
* SOURCE: any valid public media file link (also Google Drive and Dropbox shared links)
* CODE: valid embed code
* VISIBILITY: 'true' or 'false' (as string)
* FONTVARIANT: any existing font weight value from the result of the endpoint `templates/fontVariants` for ex: '300italic', '400', '700italic', etc.
* TEXTMARKDOWN: 4 markdowns could be added to text elements
  * Link - \[This is the text]\(This will be the link)
  * Italic text - text between one star - (\* will be transformed as italic text \*)
  * Bold text - text between two pairs of stars - (\*\* will be transformed as bold text \*\*)
  * Bold italic text - text between two groups of three stars - (\*\*\*  will be bold and italic text  \*\*\*)&#x20;
* TEXTCOLOR: valid hexadecimal color code (#FFF or #FFFFFF) - used with TEXT and BUTTON layers
* BGCOLOR: valid hexadecimal color code  (#FFF or #FFFFFF) - used for changing the background for BUTTON or SHAPE layers
* SVGCOLORS: valid hexadecimal color list ("#123456", "#FFFFFF", "#AAAAAA") - used for layers which has an SVG file as source&#x20;
* LINEHEIGHT - used with TEXT layers
* LETTERSPACING - used with TEXT and BUTTON layers
* FONTFAMILY - used with TEXT and BUTTON layers
* TEXTHTML - multiple valid html tags can be used with TEXT layers&#x20;
  * allowedTags: \['p', 'br', 'strong', 'b', 'em', 'i', 'u', 'a', 'ul', 'ol', 'li', 'span', 'div', 'sub', 'sup']
* ALTTEXT - any valid string. Applies to Image, video, SVG, shape and button elements

### **Response**

The response to this request

{% code title="Response example" %}

```json
{
    "response": {
        "status": "success",
        "design": {
            "hash": "3nrjeny"
        }
    }
}
```

{% endcode %}
