# The Brief Integration documentation {% hint style="info" %} Note: For Integrations established on Creatopy endpoints (deprecated).\ \ Creatopy version of our API is now officially deprecated but will continue to function during \ this grace period to support a smooth transition. Existing integrations will keep working, but we strongly recommend updating them according to this new documentation.\ \ The differences between the old and new versions are minimal: **the structure and functionality remain unchanged**, with the **only update being the domain change for endpoints.** Please update your integrations promptly to maintain full compatibility and receive the latest improvements. {% endhint %} ## Public API You can use the API to integrate The Brief with your app, allowing you to create exports using your existing designs (templates) and manage your projects, folders, designs, and more. {% content-ref url="/pages/doNkg5O0HUHYcoLfvyqV" %} [Public API](/public-api) {% endcontent-ref %} ## App Integration You can use the App Integration in order to embed The Brief within your app, allowing you to use the full capabilities & features of our Ad Studio experience. {% content-ref url="/pages/L8FCGGwr5PP6Y1F9vqXD" %} [App integration](/app-integration) {% endcontent-ref %} ## Zapier Integration Use Zapier - The Brief integration to automate generating creatives and save time on the design process. You can set various triggers in Zapier that will call the our API to generate creatives based on a template in your team and have them delivered over email or populated into your cloud storage. Follow the guide to integrate your account with other platforms. {% content-ref url="/pages/qDM8wRBzCUW7ZC8v8iBo" %} [Zapier integration](/zapier-integration) {% endcontent-ref %} # Public API You can use the API to integrate The Brief with your app, allowing you to create exports using your existing designs (templates) and manage your projects, designs, comments, and more. Additionally, you can use it in combination with our [App Integration](/app-integration) for enhanced functionality. ### Create an API key In your The Brief account, under your profile, go to **Manage account** and select **API credentials** section**.** From there you can create an API key that you'll use to communicate with the API: ### **Rate limit** * Export: 15 requests / 10 seconds / team (Exporting a design set is also considered 1 request) * Rest of the routes: 100 requests / 10 seconds / team # Authentication ### JWT Bearer token With each request to the API, we need to send an authorization token. This token is a JWT Bearer token. The first step in creating JWT tokens is to create a secret key that will be used to sign the tokens. For this, we need to generate them from the Brief App on Team Settings > API credentials. The secret key should be kept private and should not be shared with anyone. For the generation of the token, we need to have a JSON payload in which to add the public key. The payload is the data that is encoded in the token. For example, the payload for a request might look like this: ```json // payload { "clientId": '...publickey..., "iat": 1516239022 } ``` The payload needs to be signed using the secret key. This can be done using a library like `jsonwebtoken`. The resulting token will be a long string that can be passed to the client. ```javascript const jwt = require('jsonwebtoken'); const token = jwt.sign({ payload }, secretKey); ``` The client will then send the token back to the server with each request. The server can then validate the token by decoding it and checking the signature using the same secret key. In the REST API, you can generate the token using [Auth](/public-api/rest-api/auth) route. # REST API How to integrate The Brief using our REST API. **Rest API endpoint:** * `https://api.thebrief.ai/v1` # Auth ## **Auth Token Request** This endpoint is used to authenticate and obtain a token to access protected resources. The request should be made using the HTTP POST method. ### **Request** * Method: POST * Endpoint: `https://api.thebrief.ai/v1/auth/token` * Body: * `clientId` (text) - The client ID for authentication. * `clientSecret` (text) - The client's secret for authentication. ### **Response** Upon successful authentication, the server responds with a status code of 200 and a JSON object containing the authentication token. Example response: ```json { "token": "eyJhbGciOiJIUzI1NiIsInR....5cCI6IkpXVCJ9" } ``` Example payload: ```json { "clientId": "6a38ea97-129d-4171-859c-5535c9f3e4e1", "clientSecret": "27eb6a90-1938-474c-8353-1ce4514b4dcd" } ``` ```bash curl --location 'https://api.thebrief.ai/v1/auth/token' \ --header 'Content-Type: application/json' \ --data '{ "clientId": "6a38ea97-129d-4171-859c-5535c9f3e4e1", "clientSecret": "27eb6a90-1938-474c-8353-1ce4514b4dcd" }' ``` # Exports ## **Export new design (with changes)** This endpoint allows you to export templates by making an HTTP POST request. This endpoint will also create a new design with the requested element changes. ### **Request** * Method: POST * Endpoint: `https://api.thebrief.ai/v1/export-with-changes` * Body: * `templateHash` (string, required): The hash of the creative. * `type` (string, required): The type of export. * `exportSettings` (object, optional): Settings for the export * `quality` (integer, optional): HTML specific param. (Accepted values are in the range from 1 to 100). ```typescript 60 = LOW, 80 = MEDIUM, 90 = HIGH, 100 = UNCOMPRESSED, Any other value is a custom value ``` * `gifPreset` (string, optional): GIF specific param. Available values: ('highQuality', 'optimized', 'static'). * `networkId` (integer, optional): HTML specific param. * `pdfPreset` (enum, optional): PDF specific param (PDF\_STANDARD and PDF\_PRINT) * `slide` (array of integers, optional): PDF specific param (the slide number to export, starts from 0 (for the first slide)) * `scale`: (float, optional): JPG, WEBP, PNG specific param. * `targetFPS`: (integer, optional): frame rate - MP4 specific param * `retina` (boolean, optional): save retina-specific images - HTML specific param * `retinaOnly` (boolean, optional): exclude non-retina images from downloaded zip - HTML specific param * `convertCustomFonts` (boolean, optional): convert custom fonts to SVG - HTML specific param * `minifyHtml` (boolean, optional): minify HTML size - HTML specific param * `urlTarget` (enum, optional): HTML specific param (\_blank*, \_self, \_top, \_parent )* * `useAsClickTag` (boolean, optional): HTML specific param * `clickTagUrl` (string, optional): HTML specific param * `includeFallbackImage` (boolean, optional): include a .jpg format fallback image into the downloaded zip HTML specific param * `allowedSizeHashesOnly` (array of strings, optional): if the user wants to generate only a few sizes from a set, put here the list of hashes (which can be obtained using this endpoint `https://api.thebrief.ai/v1/templates/{{templateHash}}/design-sizes)` * `exportMp4V3`(boolean, optional): mp4 related param. Allow users to use the new version of the Mp4 export (by default, the export will use the old Mp4 export) * `responsiveScaling` (boolean, optional, default: true) scales the ad to fit the container it's opened in, keeping each design's aspect ratio. Turn off to render at its original size. * `webhookUrl` (string, optional): Webhook URL that will be called when the export completes (succeeds or fails) * `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): * `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. * `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. Also, this name will be included in the name of the downloaded version of the creatives. (Also, the name will be the name of the zipped version of the downloadable URLs of a design set - known as zipUrl in the response for design set) 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 \*\*\*) * 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 * 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 * allowedTags: \['p', 'br', 'strong', 'b', 'em', 'i', 'u', 'a', 'ul', 'ol', 'li', 'span', 'div', 'sub', 'sup'], IMPORTANT!! If you use a request in which the input is exactly the same as another input used earlier and the request status was 'complete', the response will be the cached result of the other request. ```bash curl --location 'https://api.thebrief.ai/v1/export-with-changes' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJ...' \ --data '{ "templateHash": "zdow6r", "type": "jpg", "elementsChanges": [ { "elementName": "Headline", "changes": [ { "attribute": "LABEL", "value": "Enjoy a $0 annual \nfee and 1.5% \n cashback on purchases" } ] }, { "elementName": "Description", "changes": [ { "attribute": "LABEL", "value": "Plus, earn a $300 bonus" }, { "attribute": "VISIBILITY", "value": "false" }, { "attribute": "FONTVARIANT", "value": "400italic" } ] }, { "elementName": "Logo", "changes": [ { "attribute": "SOURCE", "value": "https://dev.w3.org/SVG/tools/svgweb/samples/svg-files/eff.svg" } ] }, { "elementName": "shape2", "changes": [ { "attribute": "SOURCE", "value": "https://cdn.pixabay.com/photo/2012/04/24/16/43/targets-40383_1280.png" } ] }, { "elementName": "Image", "changes": [ { "attribute": "SOURCE", "value": "https://cdn.pixabay.com/photo/2012/04/24/16/43/targets-40383_1280.png" } ] }, { "elementName": "Title", "changes": [ { "attribute": "FONTFAMILY", "value": "Unbounded" } ] }, { "elementName": "Headline", "changes": [ { "attribute": "TEXTHTML", "value": "

Enjoy a $0 annual fee and 1.5% cashback on purchases

" } ] } ] }' ``` ### **Response** The response to this request is a JSON schema: {% code title="Response example" %} ```json { "response": { "export": { "id": "b46adaed-39df-41a2-89e5-beb870282414", "type": "jpg", "status": "pending", "errorLog": null, "creatives": [ { "id": "fc188412-c614-4db7-b611-f725e73cb36d", "status": "pending", "url": null }, { "id": "954dad76-6dd9-4a79-ac09-26da6bceeb96", "status": "pending", "url": null } ] } } } ``` {% endcode %} With the export ID, we will check the status of the export ## **Export existing design** This endpoint allows you to export existing designs by making an HTTP POST request. This endpoint will not create a new design. ### **Request** * Method: POST * Endpoint: `https://api.thebrief.ai/v1/export` * Body: * `creativeHash` (string, required): The hash of the creative. * `type` (string, required): The type of export. * `exportSettings` (object, optional): Settings for the export * `quality` (integer, optional): HTML specific param. * `gifPreset` (enum, optional): GIF specific param. * `networkId` (integer, optional): HTML specific param. * `pdfPreset` (enum, optional): Pdf specific param (PDF\_STANDARD and PDF\_PRINT) * `slide` (array of integers, optional): PDF specific param (the slide number to export, starts from 0 (for the first slide) * `retinaOnly` (boolean, optional): exclude non-retina images from downloaded zip - HTML specific param * `convertCustomFonts` (boolean, optional): convert custom fonts to SVG - HTML specific param * `minifyHtml` (boolean, optional): minify HTML size - HTML specific param * `urlTarget` (enum, optional): HTML specific param (\_blank*, \_self, \_top, \_parent )* * `useAsClickTag` (boolean, optional): HTML specific param * `clickTagUrl` (string, optional): HTML specific param * `includeFallbackImage` (boolean, optional): include a .jpg format fallback image into the downloaded zip HTML specific param * `allowedSizeHashesOnly` (array of strings, optional): if the user wants to generate only a few sizes from a set, put here the list of hashes (which can be obtained using this endpoint `https://api.creatopy.com/v1/templates/{{templateHash}}/design-sizes)` * `exportMp4V3`(boolean, optional): mp4 related param. Allow users to use the new version of the Mp4 export (by default, the export will use the old Mp4 export) * `responsiveScaling` (boolean, optional, default: true) scales the ad to fit the container it's opened in, keeping each design's aspect ratio. Turn off to render at its original size. * `webhookUrl` (string, optional): Webhook URL that will be called when the export completes (succeeds or fails) * `feed` (object, optional): Feed option * `rows` (string, required): Rows to be included in export. Example: * "1:10" Rows from 1 to 10 * "1,3,6" specific rows 1, 3 and 6 * “-1,-2" - last two rows (negative numbers count from end) ```bash curl --location 'https://api.thebrief.ai/v1/export' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJ...' \ --data '{ "creativeHash": "zdow6r", "type": "jpg", }' ``` ### **Response** The response to this request is a JSON schema: {% code title="Response example" %} ```json { "response": { "export": { "id": "b46adaed-39df-41a2-89e5-beb870282414", "type": "jpg", "status": "pending", "errorLog": null, "creatives": [ { "id": "fc188412-c614-4db7-b611-f725e73cb36d", "status": "pending", "url": null }, { "id": "954dad76-6dd9-4a79-ac09-26da6bceeb96", "status": "pending", "url": null } ] } } } ``` {% endcode %} With the export ID, we will check the status of the export the For design sets, we added a possibility to download all creatives from a single link. You will find the link in the response at zipUrl field. ## Check Export Status This endpoint retrieves the export data with the specified ID. ### Request * Method: GET * URL: `https://api.creatopy.com/v1/export/b46adaed-39df-41a2-89e5-beb870282414` ### Response * Status: 200 * Content-Type: application/json {% code title="Response example" %} ```json { "response": { "id": "b46adaed-39df-41a2-89e5-beb870282414", "type": "jpg", "status": "complete", "errorLog": null, "creatives": [ { "status": "complete", "url": "https://creatopy-api-0d4e56b.s3.eu-central-1.amazonaws.com/creatives/b46adaed-39df-41a2-89e5-beb870282414/fc188412-c614-4db7-b611-f725e73cb36d?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASCU4ALRBL5EQ3KHE%2F20240911%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20240911T072944Z&X-Amz-Expires=3600&X-Amz-Signature=6739d8a7f2f70b7a518c510eb10ebcbcd82fe57dec1a0c335df473257229562e&X-Amz-SignedHeaders=host", "id": "fc188412-c614-4db7-b611-f725e73cb36d" }, { "status": "complete", "url": "https://creatopy-api-0d4e56b.s3.eu-central-1.amazonaws.com/creatives/b46adaed-39df-41a2-89e5-beb870282414/954dad76-6dd9-4a79-ac09-26da6bceeb96?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASCU4ALRBL5EQ3KHE%2F20240911%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20240911T072944Z&X-Amz-Expires=3600&X-Amz-Signature=bfd48ac7717f9f4cedf60aa5d3ca0f2dbf55ec202bf8ac9829465756450489ef&X-Amz-SignedHeaders=host", "id": "954dad76-6dd9-4a79-ac09-26da6bceeb96" } ] } } ``` {% endcode %} ``` Response example for design set { "response": { "id": "b46adaed-39df-41a2-89e5-beb870282414", "type": "jpg", "status": "complete", "errorLog": null, "creatives": [ { "zipUrl": "https://creatopy-api-0d4e56b.s3.eu-central-1.amazonaws.com/creatives/f4d71ed6-c10f-41ed-9704-434b021647aa/4a56079b-6107-4db9-9214-49fbc635f761?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASCU4ALRBL5EQ3KHE%2F20250410%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20250410T130012Z&X-Amz-Expires=3600&X-Amz-Signature=6d5cb6d8a3133fa5b89529acc282e4367e5d747710bc6d945eac56a6fd9014f2&X-Amz-SignedHeaders=host", "creatives": [ { "status": "complete", "url": "https://creatopy-api-0d4e56b.s3.eu-central-1.amazonaws.com/creatives/f4d71ed6-c10f-41ed-9704-434b021647aa/4a9c1246-4de8-4b70-b59f-6d9eeab13912?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASCU4ALRBL5EQ3KHE%2F20250410%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20250410T130010Z&X-Amz-Expires=3600&X-Amz-Signature=c627d916ac8c4031d6f07a0310acd540bf02a8dfd2168a021db7e06eafbf58ff&X-Amz-SignedHeaders=host", "id": "4a9c1246-4de8-4b70-b59f-6d9eeab13912", "size": { "name": "Large Rectangle", "width": 336, "height": 280, "measureUnit": "px" }, "slideNumber": null }, { "status": "complete", "url": "https://creatopy-api-0d4e56b.s3.eu-central-1.amazonaws.com/creatives/f4d71ed6-c10f-41ed-9704-434b021647aa/662a743b-5976-4221-9808-eef7c70c4e60?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASCU4ALRBL5EQ3KHE%2F20250410%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20250410T130010Z&X-Amz-Expires=3600&X-Amz-Signature=bc4207873ae4a092d8d7ce1b67bd3db4bfd24ccf820f44f6f5b8aa417b08370d&X-Amz-SignedHeaders=host", "id": "662a743b-5976-4221-9808-eef7c70c4e60", "size": { "name": "Netboard", "width": 580, "height": 400, "measureUnit": "px" }, "slideNumber": null } ] } ] } } ``` [Creatives](https://www.notion.so/Creatives-e4113c9a5d78465fa4d62ae7ab2f79c7?pvs=21) # Creatives When you start an export, the resources generated by the export are called creatives. For example, if you export a set with multiple sizes, a creative will be generated for each size from the template design you want to modify and export. Each creative generated by an export has the type of the export (JPG, GIF, MP4…) These resources are related strictly to the API, and you will not find them anywhere in the app, with the only specification that for each creative generated, we will have a generated design in the app. All the status of the creatives can be seen directly from the export status, as in the next example: ```json { "response": { "id": "b46adaed-39df-41a2-89e5-beb870282414", "elementsChanges": null, "type": "jpg", "status": "complete", "errorLog": null, "creatives": [ { "status": "complete", "url": "https://thebrief-api-0d4e56b.s3.eu-central-1.amazonaws.com/creatives/b46adaed-39df-41a2-89e5-beb870282414/fc188412-c614-4db7-b611-f725e73cb36d?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASCU4ALRBL5EQ3KHE%2F20240911%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20240911T072944Z&X-Amz-Expires=3600&X-Amz-Signature=6739d8a7f2f70b7a518c510eb10ebcbcd82fe57dec1a0c335df473257229562e&X-Amz-SignedHeaders=host", "id": "fc188412-c614-4db7-b611-f725e73cb36d" }, { "status": "complete", "url": "https://thebrief-api-0d4e56b.s3.eu-central-1.amazonaws.com/creatives/b46adaed-39df-41a2-89e5-beb870282414/954dad76-6dd9-4a79-ac09-26da6bceeb96?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASCU4ALRBL5EQ3KHE%2F20240911%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20240911T072944Z&X-Amz-Expires=3600&X-Amz-Signature=bfd48ac7717f9f4cedf60aa5d3ca0f2dbf55ec202bf8ac9829465756450489ef&X-Amz-SignedHeaders=host", "id": "954dad76-6dd9-4a79-ac09-26da6bceeb96" } ] } } ``` If you are interested in a specific ID of a generated creative, you can call and take the status of that creative by calling the creative endpoint. ```bash curl --location 'https://api.thebrief.ai/v1/creative/fc188412-c614-4db7-b611-f725e73cb36d' \ --header 'Authorization: Bearer eyJ...' ``` Response example: ```json { "response": { "status": "complete", "url": "https://thebrief-api-0d4e56b.s3.eu-central-1.amazonaws.com/creatives/b46adaed-39df-41a2-89e5-beb870282414/fc188412-c614-4db7-b611-f725e73cb36d?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASCU4ALRBL5EQ3KHE%2F20240911%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20240911T140349Z&X-Amz-Expires=3600&X-Amz-Signature=6d71919d3572df0321b527034b75237062fc370d4c4beb987f97bee537075b5f&X-Amz-SignedHeaders=host", "id": "fc188412-c614-4db7-b611-f725e73cb36d" } } ``` Another scenario when this can be useful is if you need to take the creative URL after more than a day; the provided URL is available for only one hour. But if you call this again after that period, another one-hour valid URL is provided. # Templates (Designs) ## List Templates (designs) List all templates you have access to with the user assigned to the credentials. This endpoint makes an HTTP GET request to retrieve a list of templates from the specified API endpoint. {% hint style="info" %} Templates are now managed under Brand Kits as Brand Templates, rather than through this Templates endpoint. \ For template-related operations, use the designated [Brand Templates](https://docs.thebrief.ai/public-api/rest-api/brand-kits/brand-templates) endpoint. For design-related operations, use the corresponding [Designs](https://docs.thebrief.ai/public-api/rest-api/designs) endpoint. {% endhint %} ### **Request** * Method: GET * Endpoint: `https://api.thebrief.ai/v1/templates` * Query Parameters: * `keyword` (string, optional): The keyword to search for a template name * `projectId` (string, optional): Return only templates from a specific project * `folderId` (string, optional): Return only templates from a specific folder * `limit` (integer, optional): The maximum number of templates 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) * `onlyTemplates` (boolean, optional): Return only designs (marked as custom templates) from a team * `exactSearch` (boolean, optional): If true, it will return only the templates with the name equal to the keyword. (For ex. keyword = 'Template 1' will return only designs with the name 'Template 1') * `orderBy` (enum, optional): option to order the response results by the next fields: ```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: ```bash curl --location 'https://api.thebrief.ai/v1/templates' \ --header 'Authorization: Bearer eyJ...' ``` Response example: ```json { "response": { "nodes": [ { "id": "3pqqql", "name": "Untitled design", "isTemplate": true, "projectId": 826801, "folderId": 152322, "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", "isTemplate": true, "projectId": 826801, "folderId": 512322, "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", "isTemplate": true, "projectId": 826801, "folderId": 243454, "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", "isTemplate": false, "projectId": 826801, "folderId": 12555, "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", "isTemplate": true, "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", "isTemplate": false, "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", "isTemplate": true, "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. ## Delete Template (design) This endpoint allows you to delete a design (template). ### Request * Method: DELETE * Endpoint: `https://api.thebrief.ai/v1/templates` * Body: * `hash` (string, required): The hash of the template(design) you want to be deleted. ```bash Request example curl --location --request DELETE 'https://api.thebrief.ai/v1/templates' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJhdXRobSVV6STFOa...' \ --data '{ "hash": "rfg5d6" }' ``` ### Response The response will be in JSON format: ``` { "response": { status": "success" } } ``` # Elements ### Retrieve Elements of a Template This endpoint retrieves the elements of a specific template. Using these elements, you can get an idea of what you want to modify in the export to a specific template. ### Request * Method: GET * URL: `https://api.thebrief.ai/v1/templates/zdow6r/elements` ### Response The response is a JSON object with the following schema: JSON ```json { "type": "object", "properties": { "response": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "layerType": { "type": "string" }, "attributeChangeType": { "type": "string" }, "value": { "type": "string" }, "slideNumber": { "type": "integer" }, "gotoUrl": { "type": "string" }, } } } } } ``` The response body contains an array of elements, where each element object includes the `name`, `layerType`, `attributeChangeType`, `value`, and `slideNumber` properties. Request example: ```bash curl --location 'https://api.thebrief.ai/v1/templates/zdow6r/elements' \ --header 'Authorization: Bearer eyJhdXRob3JpemF0aW9uIjoiQmVhcmVyIGV5SmhiR2NpT2lKSVV6STFOaUlzSW5SNWNDSTZJa3BYVkNKOS5leUpwWVhRaU9qRTJPREV4TVRVMU56YzVPRElzSW1Oc2FXVnVkRWxrSWpvaU16QmpaalJsTldRdE1XRmxOQzAwT1RrNExUa3lNV010TVdVMU5qZzJOemd4WW1VeEluMC56WlRDX0ZHZW5FdklRZHhZTlk1cW9OWnlxSEdEOUYtTUtpNm1uV0h6V1NvIiwiYWxnIjoiSFMyNTYifQ.eyJjbGllbnRJZCI6IjZhMzhlYTk3LTEyOWQtNDE3MS04NTljLTU1MzVjOWYzZTRlMSJ9.gWvLWJSqk0bSO78t5xxdYcR08KHAyvQtKCxd0mnlK5U' ``` Response example: ```json { "response": [ { "name": "Image", "layerType": "image", "attributeChangeType": "SOURCE", "value": "ogw3y", "slideNumber": 0, "gotoUrl": "https://www.google.com" }, { "name": "E-mail", "layerType": "text", "attributeChangeType": "LABEL", "value": "oliver.jackson@properties.com", "slideNumber": 0, "gotoUrl": null }, { "name": "Tel Number", "layerType": "text", "attributeChangeType": "LABEL", "value": "980.930.7825", "slideNumber": 0, "gotoUrl": null }, { "name": "Name", "layerType": "text", "attributeChangeType": "LABEL", "value": "Oliver Jackson", "slideNumber": 0, "gotoUrl": null }, { "name": "Headline", "layerType": "text", "attributeChangeType": "LABEL", "value": "Buy or sell with confidence", "slideNumber": 0, "gotoUrl": null }, { "name": "Logo", "layerType": "svg", "attributeChangeType": "SOURCE", "value": "qozx", "slideNumber": 0, "gotoUrl": null }, { "name": "Image 1", "layerType": "image", "attributeChangeType": "SOURCE", "value": "ogw3y", "slideNumber": 1, "gotoUrl": null }, { "name": "Headline 1", "layerType": "text", "attributeChangeType": "LABEL", "value": "Buy or sell with confidence", "slideNumber": 1, "gotoUrl": null }, { "name": "Logo 1", "layerType": "svg", "attributeChangeType": "SOURCE", "value": "qozx", "slideNumber": 1, "gotoUrl": null }, { "name": "E-mail 1", "layerType": "text", "attributeChangeType": "LABEL", "value": "oliver.jackson@properties.com", "slideNumber": 1, "gotoUrl": null }, { "name": "Tel Number 1", "layerType": "text", "attributeChangeType": "LABEL", "value": "980.930.7825", "slideNumber": 1, "gotoUrl": null }, { "name": "Name 1", "layerType": "text", "attributeChangeType": "LABEL", "value": "Oliver Jackson", "slideNumber": 1, "gotoUrl": null } ] } ``` # Template Sizes ## List Template Sizes (design) This endpoint is used to get the design sizes of a design (template). The design could be a design set or a single design. ### Request * Method: GET * Endpoint: `https://api.thebrief.ai/v1/templates/{{templateHash}}/design-sizes` Request example: ```bash curl --location 'https://api.thebrief.ai/v1/templates/lpp55x/design-sizes' \ --header 'Authorization: Bearer eyJ...' ``` ### Response The response will be in JSON format: ``` { "response": [ { "hash": "rd", "name": "Square", "kind": "system_design", "width": 250, "height": 250, "measureUnit": "px" }, { "hash": "xdook", "name": "Custom size 8", "kind": "custom_design", "width": 120, "height": 130, "measureUnit": "px" } ] } ``` # Font variants ### Retrieve font variants for a layer of a template This endpoint retrieves the font variants (weight and style combination) of a text layer's fonts of a specific template. ### Request * Method: GET * URL: `https://api.thebrief.ai/v1/templates/fontVariants` * Body: * `templateHash` (string, required): The hash of the template. * `layerName` (string, required): The name of the layer of export. ### Response The response is a JSON object with the following schema: JSON ```json { "response": [ { "name": "Description", "fontFamilyType": "google", "slideNumber": 0, "bannersetElementId": 7, "fontFamily": "Roboto Condensed", "actualFontStyle": "normal", "actualFontWeight": 400, "fontVariants": [ { "weight": "300", "subFamily": "Light" }, { "weight": "400", "subFamily": "Regular" }, { "weight": "700", "subFamily": "Bold" }, { "weight": "300italic", "subFamily": "Light Italic" }, { "weight": "400italic", "subFamily": "Regular Italic" }, { "weight": "700italic", "subFamily": "Bold Italic" } ] } ] } ``` When you use the FONTVARIANT attribute on related endpoints, as value, you will use the weight value from the response. # ShareLink ## ShareLink This endpoint retrieves the share link URL for a specific templateHash, which is working with generated Templates(variants). ### Request * Method: GET * URL: `https://api.thebrief.ai/v1/shareLink/{{templateHash}}` Request example: ```bash curl --location 'https://api.thebrief.ai/v1/shareLink/zdow6r' \ --header 'Authorization: Bearer eyJ...' ``` ### Response The response will be a JSON object with the following schema: JSON ```bash { "response": { "shareLinkUrl": "https://app.thebrief.ai/share/d/5x6ze0x1q6zq", "comments": { "threads": [] } } } ``` ## Generate ShareLink (with changes) This endpoint allows you to generate a preview based on the provided template and element changes. ### Request * Method: POST * URL: `https://api.thebrief.ai/v1/shareLink/generate` * Body: * `templateHash` (string, required): The hash of the creative. (template or design) * `elementsChanges` (array, required): * `elementName` (string, required): The name of the element. * `changes` (array, required): * `attribute` (string, required): The attribute to be changed. (Available attributes are: "LABEL", "SOURCE", "CODE", "VISIBILITY", "FONTVARIANT", "TEXTMARKDOWN", "TEXTCOLOR", "BGCOLOR", "SVGCOLORS", "LINEHEIGHT", "LETTERSPACING" and "FONTFAMILY" ) * `value` (string, required): The new value for the attribute. * `generalChanges` (object, optional): * `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 are (depending on attribute): * LABEL: any valid string * SOURCE: any valid public media file link * 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 * \[This is the text]\(This will be the link) * text between one star - *italic text* (\* will be transformed as italic text \*) * text between two pairs of stars - **bold text** (\* \* will be transformed as bold text \* \*) ( no spaces between those 2 stars) * text between two groups of three stars - ***bold italic text*** (\* \* \* will be bold transformed as italic text \* \* \*) (no spaces between those 3 stars) * 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 * LINEHEIGHT - used with TEXT layers * LETTERSPACING - used with TEXT and BUTTON layers * FONTFAMILY - used with TEXT and BUTTON layers **Response:** The response for this request is a JSON object following the schema below: ```json { "response": { "shareLinkUrl": "https://app.thebrief.ai/share/d/0z6w0dg027ol" } } ``` ```bash curl --location 'https://api.thebrief.ai/v1/sharelink/generate' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJ...' \ --data '{ "templateHash": "2kzq51", "elementsChanges": [ { "elementName": "Headline", "changes": [ { "attribute": "LABEL", "value": "Enjoy a $0 annual \nfee and 1.5% \n cashback on purchases" }, { "attribute": "VISIBILITY", "value: "false" } ] }, { "elementName": "Description", "changes": [ { "attribute": "LABEL", "value": "Plus, earn a $300 bonus" }, { "attribute": "FONTVARIANT", "value": "italic300" } ] }, { "elementName": "Logo", "changes": [ { "attribute": "SOURCE", "value": "https://dev.w3.org/SVG/tools/svgweb/samples/svg-files/eff.svg" } ] }, { "elementName": "shape2", "changes": [ { "attribute": "SOURCE", "value": "https://cdn.pixabay.com/photo/2012/04/24/16/43/targets-40383_1280.png" } ] }, { "elementName": "Image", "changes": [ { "attribute": "SOURCE", "value": "https://cdn.pixabay.com/photo/2012/04/24/16/43/targets-40383_1280.png" } ] }, { "elementName": "Title", "changes": [ { "attribute": "FONTFAMILY", "value": "Unbounded" } ] } ] }' ``` ```json { "response": { "shareLinkUrl": "https://app.thebrief.ai/share/d/dp7ke1g347o5" } } ``` # Projects ## List projects This endpoint makes an HTTP GET request to retrieve a list of projects based on the provided keyword, with a specified limit and cursor for pagination ### Request * Method: GET * Endpoint: `https://api.thebrief.ai/v1/projects` * Query Parameters: * `keyword` (string, optional): The keyword to search for projects. * `limit` (integer, optional): The maximum number of projects to be returned. * `cursor` (string, optional): A cursor for pagination. * `orderBy` (enum, optional): option to order the response results by the next fields: ```typescript ID NAME CREATED_AT UPDATED_AT ``` * `orderDirection` (enum, optional): option to order the response by direction: ``` ASC DESC ``` ```bash curl --location 'https://api.thebrief.ai/v1/projects?keyword=Levai&limit=10&cursor=eyJsaW1pdCI6MSwibGFzdElkIjozOTE3MzQzfQ%3D%3D' \ --header 'Authorization: Bearer eyJh...' ``` ### Response Upon a successful execution, the response will have a status code of 200 and a JSON content type. The response body will contain the following structure: JSON ```json { "response": { "totalCount": 0, "nodes": [ { "id": 0, "name": "", "createdBy": 0, "color": null, "description": null, "brandKit": { "id": 0, "name": "" } } ], "pageInfo": { "hasNextPage": true, "endCursor": "" } } } ``` The `totalCount` indicates the total number of projects found, while the `nodes` array contains the project details such as `id`, `name`, `createdBy`, `color`, `description`, and `brandKit`. The `pageInfo` object specifies if there are more pages available for pagination, along with the `endCursor` for the next page. ```json { "response": { "totalCount": 10, "nodes": [ { "id": 3102440, "name": "api created user's project", "createdBy": 719026, "color": null, "description": null, "brandKit": { "id": 1224286, "name": "Lets tag this to project" } }, { "id": 3102437, "name": "api created user's project", "createdBy": 719026, "color": null, "description": null, "brandKit": { "id": 1224286, "name": "Lets tag this to project" } }, { "id": 2898068, "name": "Samuel Negru's project", "createdBy": 141, "color": null, "description": null, "brandKit": { "id": 1224286, "name": "Lets tag this to project" } }, ... { "id": 2400300, "name": "Vridhi QA's project", "createdBy": 719026, "color": null, "description": null, "brandKit": { "id": 1224286, "name": "Lets tag this to project" } }, { "id": 2313714, "name": "Tibi Orosz's project", "createdBy": 719026, "color": null, "description": null, "brandKit": { "id": 1224286, "name": "Lets tag this to project" } } ], "pageInfo": { "hasNextPage": true, "endCursor": "eyJsaW1pdCI6MTAsImxhc3RJZCI6MjMxMzcxNH0=" } } } ``` ## Create Project This endpoint allows you to create a new project. ### Request * Method: POST * Endpoint: `https://api.thebrief.ai/v1/projects` * Body: * `name` (string, required): The name of the project. * `brandKitId` (integer, required): The ID of the brand kit associated with the project. ### Response The response of this request can be documented as a JSON schema: JSON ```json { "type": "object", "properties": { "response": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "integer" }, "teamId": { "type": "integer" }, "name": { "type": "string" }, "createdBy": { "type": "integer" }, "color": { "type": "string" }, "description": { "type": ["string", "null"] }, "brandKit": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "teamId": { "type": "integer" }, "typography": { "type": "array", "items": { "type": "object", "properties": { "fontId": { "type": ["integer", "null"] }, "fontName": { "type": "string" }, "fontSize": { "type": "integer" }, "fontWeight": { "type": "string" }, "type": { "type": "string" } } } }, "createdBy": { "type": "integer" } } } } } } } ``` ## Delete Project This endpoint allows you to delete a project. ### Request * Method: DELETE * Endpoint: `https://api.thebrief.ai/v1/projects` * Body: * `projectId` (integer, required): The ID of the project you want to delete. {% code title="Request example" %} ```bash curl --location --request DELETE 'https://api.thebrief.ai/v1/projects' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJhdXRob3JpemF0aW9uIjoiQmVhcmVyIGV5SmhiR2NpT2lKSVV6STFOaUlzSW5SNWNDSTZJa3BYVkNKOS5leUpwWVhRaU9qRTJPREV4TVRVMU56YzVPRElzSW1Oc2FXVnVkRWxrSWpvaU16QmpaalJsTldRdE1XRmxOQzAwT1RrNExUa3lNV010TVdVMU5qZzJOemd4WW1VeEluMC56WlRDX0ZHZW5FdklRZHhZTlk1cW9OWnlxSEdEOUYtTUtpNm1uV0h6V1NvIiwiYWxnIjoiSFMyNTYifQ.eyJjbGllbnRJZCI6IjZhMzhlYTk3LTEyOWQtNDE3MS04NTljLTU1MzVjOWYzZTRlMSJ9.gWvLWJSqk0bSO78t5xxdYcR08KHAyvQtKCxd0mnlK5U' \ --data '{ "projectId": 123 }' ``` {% endcode %} ### Response ``` { "response": { "status": "success" } } ``` ## Update projects This endpoint allows you to update the name and the assigned brandkit for a project. ### Request * Method: `PUT` * Endpoint: `https://api.thebrief.ai/v1/projects` * Body: * `projectId` (integer, required): The project id * `name` (string, optional): The new name of the project. * `assignedBrandKitId` (integer, optional): The id of the assigned brandkit. * `isBrandKitSelectable` (boolean, optional): true if brandkits are selectable from Editor. ### Response The response will be in JSON format with the following structure: ```graphql { "type": "object", "properties": { "response": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "integer" }, "teamId": { "type": "integer" }, "name": { "type": "string" }, "createdBy": { "type": "integer" }, "color": { "type": "string" }, "description": { "type": ["string", "null"] }, "brandKit": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "teamId": { "type": "integer" }, "typography": { "type": "array", "items": { "type": "object", "properties": { "fontId": { "type": ["integer", "null"] }, "fontName": { "type": "string" }, "fontSize": { "type": "integer" }, "fontWeight": { "type": "string" }, "type": { "type": "string" } } } }, "createdBy": { "type": "integer" } } } } } } } ``` # Project Users ## List project users This endpoint makes an HTTP GET request to retrieve a list of user for a project ### Request * Method: GET * Endpoint: `https://api.thebrief.ai/v1/project/users` * Query Parameters: * `projectId` (integer, required): The projectId in which will search for users ```bash curl --location 'https://api.thebrief.ai/v1/project/users' \ --header 'Authorization: Bearer eyJh...' ``` ### Response Upon a successful execution, the response will have a status code of 200 and a JSON content type. The response body will contain the following structure: JSON ```json { "response": [ { "userId": 111111, "teamId": 111, "name": "User Name 1", "url": null, "email": "user@email.com", "profilePicture": null, "role": "Admin", "teamRoleId": 1 }, { "userId": 22222, "teamId": 111, "name": "User Name 2", "url": null, "email": "user2@email.com", "profilePicture": null, "role": "Admin", "teamRoleId": 1 }, ] } ``` ## Add User to Project This endpoint allows you to add a user to a project. ### Request * Method: POST * Endpoint: `https://api.thebrief.ai/v1/project/users` * Body: * `userId` (integer, required): The ID of the user. * `projectId` (integer, required): The ID of the project where we want to add the user ### Response The response of this request can be documented as a JSON schema: JSON ```json { "response": { "status": "success" } } ``` ## Remove User from a Project This endpoint allows you to remove a user from a project. ### Request * Method: DELETE * Endpoint: `https://api.thebrief.ai/v1/project/users` * Body: * `userId` (integer, required): The ID of the user. * `projectId` (integer, required): The ID of the project from where we want to remove the user ### Response ``` { "response": { "status": "success" } } ``` # Brand Kits ## List brand kits This endpoint makes an HTTP GET request to retrieve brand kits. ### Request * Method: GET * Endpoint: `https://api.thebrief.ai/v1/brandkits` * Query Parameters: * `keyword` (string, optional): The keyword to search brand kits. * `limit` (integer, optional) : The maximum number of brand kits to retrieve. * `cursor` (string, optional): A cursor for pagination. * `orderBy` (enum, optional): option to order the response results by next fields: ```typescript ID NAME CREATED_AT UPDATED_AT ``` * `orderDirection` (enum, optional): option to order the response by direction: ``` ASC DESC ``` ```bash curl --location 'https://api.thebrief.ai/v1/brandkits?keyword=api&limit=10' \ --header 'Authorization: Bearer ey...' ``` ### Response The response will be in JSON format with the following structure: * `totalCount` (integer) - The total count of brand kits matching the search criteria. * `nodes` (array) - An array of brand kit nodes. * `pageInfo` (object) - Information about the pagination, including whether there is a next page and the end cursor. ```json { "response": { "totalCount": 0, "nodes": [], "pageInfo": { "hasNextPage": true, "endCursor": "" } } } ``` ## Create brand kit This endpoint allows you to create a new brand kit. ### Request * Method: POST * Endpoint: `https://api.thebrief.ai/v1/brandkits/create` * Body: * `name` (string, required): The name of the brand kit. * `brandName` (string, optional): The name of the brand. * `website` (string, optional): The website of the brand. * `description` (string, optional): The description of the brand. * `voice` (string, optional): The voice of the brand. * `tone` (array, optional): The tones of the brand. ### Response The response is a JSON object with the following schema: ```json { "response": { "brandKit": { "id": number, "name": string, "website": string, "description": string, "voice": string, "tone": [string], } } } ``` ## Delete brand kit This endpoint allows you to delete a brand kit. ### Request * Method: DELETE * Endpoint: `https://api.thebrief.ai/v1/brandkits` * Body: * `brandkitId` (integer, required): The ID of the brandkit you want to be deleted. {% code title="Request example" %} ```bash curl --location --request DELETE 'https://api.thebrief.ai/v1/brandkits' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJhdXRob3JpemF0aW9uIjoiQmVhcmVyIGV5SmhiR2NpT2lKSVV6STFOaUlzSW5SNWNDSTZJa3BYVkNKOS5leUpwWVhRaU9qRTJPREV4TVRVMU56YzVPRElzSW1Oc2FXVnVkRWxrSWpvaU16QmpaalJsTldRdE1XRmxOQzAwT1RrNExUa3lNV010TVdVMU5qZzJOemd4WW1VeEluMC56WlRDX0ZHZW5FdklRZHhZTlk1cW9OWnlxSEdEOUYtTUtpNm1uV0h6V1NvIiwiYWxnIjoiSFMyNTYifQ.eyJjbGllbnRJZCI6IjZhMzhlYTk3LTEyOWQtNDE3MS04NTljLTU1MzVjOWYzZTRlMSJ9.gWvLWJSqk0bSO78t5xxdYcR08KHAyvQtKCxd0mnlK5U' \ --data '{ "brandkitId": 123 }' ``` {% endcode %} ### Response ``` { "response": { "status": "success" } } ``` ## Update brand kit This endpoint allows you to update the name of a brand kit. ### Request * Method: `PUT` * Endpoint: `https://api.thebrief.ai/v1/brandkits` * Body: * `brandkitId` (integer, required): The brandkit ID * `name` (string, optional): The new name of the brandkit. * `brandName` (string, optional): The name of the brand. * `website` (string, optional): The website of the brand. * `description` (string, optional): The description of the brand. * `voice` (string, optional): The voice of the brand. * `tone` (array, optional): The tones of the brand. ### Response The response will be in JSON format with the following structure: ```graphql { "response": { "brandKit": { "id": number, "name": string, "website": string, "description": string, "voice": string, "tone": [string], } } } ``` # Brand kit logos ## Upload brand kit logos This endpoint makes an HTTP GET request to upload logos to a brand kit. ### Request * Method: POST * Endpoint: `https://api.thebrief.ai/v1/brandkit/uploadLogos` * Body: * `brandkitId` (integer, required): The id of the brand kit. * `sources` (\[string], required): The source url of the logos. ``` curl --location 'https://api.thebrief.ai/v1/brandkit/uploadLogos' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJ...' \ --data '{ "brandkitId": 123456, "sources": [ 'https://dev.w3.org/SVG/tools/svgweb/samples/svg-files/eff1.svg', 'https://dev.w3.org/SVG/tools/svgweb/samples/svg-files/eff2.svg', ] }' ``` Valid media file extensions: * jpg, jpeg, png, svg Max sizes for media files: 20 MB. For now, we only allow uploading from valid public direct links, not from Google Drive, Dropbox, or other sources. ### Response The response will be in JSON format with the following schema: ```json { "response": [ { "id": 494270, "hash": "zp1o5x", "name": "eff1", "fileName": "eff1.svg", "type": "IMAGE", "format": "svg", "status": "VALID", "height": 84, "width": 120, "size": 370, "duration": null, "url": null, "createdBy": 50, "createdByUser": { "id": 50, "name": "User Name" } } ] } ``` # Brand kit logo folders ### List brand kit logo folders This endpoint makes an HTTP GET request to retrieve the logo folders of a brand kit. #### Request **Method:** GET\ **Endpoint:** `https://api.thebrief.ai/v1/brandkits/logos/folders`\ **Query parameters:** * `brandkitId` (integer, **required**): The id of the brand kit. * `parentId` (integer, optional): If provided, returns only folders nested under this parent. Omit to list root-level folders. {% code overflow="wrap" %} ``` curl --location 'https://api.thebrief.ai/v1/brandkits/logos/folders?brandkitId=123456' \ --header 'Authorization: Bearer eyJ...' ``` {% endcode %} #### Response The response will be in JSON format with the following schema: {% code overflow="wrap" %} ```json { "response": [ { "id": 10, "name": "Primary logos", "parentId": null }, { "id": 11, "name": "Dark variants", "parentId": 10 } ] } ``` {% endcode %} *** ### Create a brand kit logo folder This endpoint makes an HTTP POST request to create a new logo folder in a brand kit. #### Request **Method:** POST\ **Endpoint:** `https://api.thebrief.ai/v1/brandkits/logos/folders`\ **Body:** * `brandkitId` (integer, **required**): The id of the brand kit. * `name` (string, **required**): The folder display name. * `parentId` (integer, optional): The parent folder id. Omit to create at the root level. {% code overflow="wrap" %} ``` curl --location 'https://api.thebrief.ai/v1/brandkits/logos/folders' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJ...' \ --data '{ "brandkitId": 123456, "name": "Seasonal", "parentId": 10 }' ``` {% endcode %} #### Response The response will be in JSON format with the following schema: {% code overflow="wrap" %} ```json { "response": { "id": 42, "name": "Seasonal", "parentId": 10 } } ``` {% endcode %} *** ### Rename a brand kit logo folder This endpoint makes an HTTP PUT request to rename a logo folder in a brand kit. #### Request **Method:** PUT\ **Endpoint:** `https://api.thebrief.ai/v1/brandkits/logos/folders`\ **Body:** * `brandkitId` (integer, **required**): The id of the brand kit. * `folderId` (integer, **required**): The id of the folder to rename. * `name` (string, **required**): The new folder name. {% code overflow="wrap" %} ``` curl --location --request PUT 'https://api.thebrief.ai/v1/brandkits/logos/folders' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJ...' \ --data '{ "brandkitId": 123456, "folderId": 42, "name": "Holiday logos" }' ``` {% endcode %} #### Response The response will be in JSON format with the following schema: {% code overflow="wrap" %} ```json { "response": { "id": 42, "name": "Holiday logos", "parentId": 10 } } ``` {% endcode %} *** ### Delete a brand kit logo folder This endpoint makes an HTTP DELETE request to delete a logo folder from a brand kit. #### Request **Method:** DELETE\ **Endpoint:** `https://api.thebrief.ai/v1/brandkits/logos/folders`\ **Body:** * `brandkitId` (integer, **required**): The id of the brand kit. * `folderId` (integer, **required**): The id of the folder to delete. {% code overflow="wrap" %} ``` curl --location --request DELETE 'https://api.thebrief.ai/v1/brandkits/logos/folders' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJ...' \ --data '{ "brandkitId": 123456, "folderId": 42 }' ``` {% endcode %} #### Response The response will be in JSON format with the following schema: {% code overflow="wrap" %} ```json { "response": { "success": true } } ``` {% endcode %} ***
# Brand kit colors ## List brand kit color palettes This endpoint makes an HTTP GET request to list the color palettes of a brand kit. ### Request * Method: GET * Endpoint: `https://api.thebrief.ai/v1/brandkit/{brandkitId}/colors` ``` curl -X 'GET' \ 'https://api.thebrief.ai/v1/brandkit/{brandkitId}/colors \ -H 'Authorization: Bearer eyJ...' ``` ### Response The response will be in JSON format with the following schema: ```json { "response": { "brandKitColorPalettes": [ { "id": number, "name": string, "colors": [ { "name": string | null, "hex": string } ], } ] } } ``` ## Create brand kit color palette This endpoint allows you to create a color palettes in a brand kit. ### Request * Method: POST * Endpoint: `https://api.thebrief.ai/v1/brandkit/{brandkitId}/colors` * Body: * `name` (integer, optional): The name of the color palette. * `colors` (array, required): The array of colors in the color palette. (can be an empty array) * `name` (string, optional): The name of the color. * `hex` (string, required): Hex code of the color ``` curl -s -X POST \ 'https://api.thebrief.ai/v1/brandkit/{brandkitId}/colors' \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"name":"Palette name","colors":[{"hex":"#ffffff","name":"white"},{"hex":"#33FF57"}]}' ``` ### Response The response will be in JSON format with the following schema: ```json { "response": { "id": number, "name": string, "colors": [ { "name": string | undefined, "hex": string } ], } } ``` ## Delete brand kit color palette This endpoint allows you to delete a color palette from a brandkit. ### Request * Method: DELETE * Endpoint: `https://api.thebrief.ai/v1/brandkit/{brandkitId}/colors` * Body: * `paletteId` (integer, required): The ID of the color palette you want to be deleted. ``` curl -s -X DELETE \ 'https://api.thebrief.ai/v1/brandkit/1333124/colors' \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"paletteId":1377221}' ``` ### Response ``` { "response": { "status": "success" } } ``` ## Update brand kit color palette This endpoint allows you to update a color palette in a brand kit. ### Request * Method: PUT * Endpoint: `https://api.thebrief.ai/v1/brandkit/{brandkitId}/colors` * Body: * `paletteId` (integer, optional): The id of the color palette. * `name` (integer, optional): The name of the color palette. * `colors` (array, required): The array of colors in the color palette. (can be an empty array) * `name` (string, optional): The name of the color. * `hex` (string, required): Hex code of the color ``` curl -s -X PUT \ 'https://api.thebrief.ai/v1/brandkit/{brandkitId}/colors' \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"paletteId":11222,"name":"Palette name","colors":[{"hex":"#ffffff","name":"white"}]}' ``` ### Response The response will be in JSON format with the following schema: ```json { "response": { "id": number, "name": string, "colors": [ { "name": string | undefined, "hex": string } ], } } ``` # Brand kit fonts ## List brand kit fonts This endpoint makes an HTTP GET request to list the fonts of a brandkit. ### Request * Method: GET * Endpoint: `https://api.thebrief.ai/v1/brandkit/{brandkitId}/fonts` ``` curl -X 'GET' \ 'https://api.thebrief.ai/v1/brandkit/{brandkitId}/fonts \ -H 'Authorization: Bearer eyJ...' ``` ### Response The response will be in JSON format with the following schema: ```json { "response": { "fonts": [ { "id": number, "name": string, "family": string, "subFamily": string, "weight": number, "version": string, "fontFamilyUrl": string, "fontFaceUrl": string } ] } } ``` ## Upload brand kit fonts This endpoint allows you to upload a font in a brand kit. ### Request * Method: POST * Endpoint: `https://api.thebrief.ai/v1/brandkit/{brandkitId}/fonts` * Body: * `file` (multipart/form data, required): The font file to upload (TTF, OTF and WOFF). ``` curl -X POST https://api.thebrief.ai/v1/brandkit/{brandkitId}/fonts \ -H "Authorization: Bearer " \ -F "file=@/path/to/font.ttf" \ -F "name=My Font Name" ``` ### Response The response will be in JSON format with the following schema: ```json { "response": { "id": number, "name": string, "family": string, "subFamily": string, "weight": number, "version": string, "fontFamilyUrl": string, "fontFaceUrl": string } } ``` ## Delete brand kit fonts This endpoint allows you to delete a font from a brandkit. ### Request * Method: DELETE * Endpoint: `https://api.thebrief.ai/v1/brandkit/{brandkitId}/fonts` * Body: * `fontId` (number, required): The id of the font to delete. ``` curl -X DELETE https://api.thebrief.ai/v1/brandkit/{brandkitId}/fonts \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"fontId": }' ``` ### Response ``` { "response": { "status": "success" } } ``` ### # Brand kit assets ## List brand kit assets This endpoint makes an HTTP GET request to list the assets of a brand kit. ### Request * Method: GET * Endpoint: `https://api.thebrief.ai/v1/brandkit/{brandkitId}/assets` * Query Params: * `first` (integer, optional): Limit the number of brandkit assets returned. * `cursor` (string, optional): Cursor used for pagination. * `parentId` : (integer, optional): The parent folder id if you want to limit the query for assets only in this folder. * `search` (string, optional): Search keyword for the brandkit assets. * `mediaFormat`: (enum, optional): Filter by media format. A possible value could be
```typescript jpg png swf gif svg wav ogg mpeg mp4 mp3 webm mov mkv avi ``` * `mediaType` (enum, optional): Filter by media type. A possible value could be
```typescript IMAGE VIDEO AUDIO ``` ``` curl -X 'GET' \ 'https://api.thebrief.ai/v1/brandkit/{brandkitId}/assets?first=5' \ -H 'accept: */*' \ -H 'Authorization: Bearer eyJ...' ``` ### Response The response will be in JSON format with the following schema: ```json { "response": { "id": 734226, "name": "Brandkit Name", "elements": { "nodes": [ { "id": 496163, "fileName": "LEGO_logo.svg", "type": "IMAGE", "format": "svg", "checksum": "57bacd0c848bc3271c6d1e1052b82530", "createdAt": "2025-01-24T15:06:51.796Z", "createdBy": 123863, "createdByUser": { "id": 123863, "name": "User Name" } ], "pageInfo": { "endCursor": "eyJjcmVhdGVkQXQiOjE3MzU1NjY1NTAwMzN9", "hasNextPage": true }, "totalCount": 48 } } } ``` ## Upload brand kit assets This endpoint makes an HTTP POST request to upload assets to a brand kit. ### Request * Method: POST * Endpoint: `https://api.thebrief.ai/v1/brandkit/uploadAssets` * Body: * `brandkitId` (integer, required): The id of the brand kit. * `mediaFolderId` (integer, optional): The id of the media folder inside the brand kit. * `sources` (\[string], required): The source url of the assets. ``` curl --location 'https://api.thebrief.ai/v1/brandkit/uploadAssets' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJ...' \ --data '{ "brandkitId": 123456, "mediaFolderId:" 65765, "sources": [ 'https://dev.w3.org/SVG/tools/svgweb/samples/svg-files/eff1.svg', 'https://dev.w3.org/SVG/tools/svgweb/samples/svg-files/eff2.svg', ] }' ``` Valid media file extensions: * mp3, wav, ogg for audio files * mp4, mov, avi, webm, mkv for video files * jpg, jpeg, png, gif, svg for image files Max sizes for media files: 20 MB for images (1MB for gifs) , 10MB for audio files and 100 MB for video files. Also max duration for video and audio files is set to 5 mins. For now, we only allow uploading from valid public direct links, but not from google drive, dropbox or other sources. ### Response The response will be in JSON format with the following schema: ```json { "response": [ { "id": 494270, "hash": "zp1o5x", "name": "eff1", "fileName": "eff1.svg", "type": "IMAGE", "format": "svg", "status": "VALID", "height": 84, "width": 120, "size": 370, "duration": null, "url": null, "createdBy": 50, "createdByUser": { "id": 50, "name": "User Name" } } ] } ``` # Brand kit asset folders ### List brand kit asset folders This endpoint makes an HTTP GET request to retrieve the asset folders of a brand kit. #### Request **Method:** GET\ **Endpoint:** `https://api.thebrief.ai/v1/brandkits/assets/folders`\ **Query parameters:** * `brandkitId` (integer, **required**): The id of the brand kit. * `parentId` (integer, optional): If provided, returns only folders nested under this parent. Omit to list root-level folders. {% code overflow="wrap" %} ``` curl --location 'https://api.thebrief.ai/v1/brandkits/assets/folders?brandkitId=123456' \ --header 'Authorization: Bearer eyJ...' ``` {% endcode %} #### Response The response will be in JSON format with the following schema: {% code overflow="wrap" %} ```json { "response": [ { "id": 100, "name": "Product photos", "parentId": null }, { "id": 101, "name": "Lifestyle shots", "parentId": 100 } ] } ``` {% endcode %} *** ### Create a brand kit asset folder This endpoint makes an HTTP POST request to create a new asset folder in a brand kit. #### Request **Method:** POST\ **Endpoint:** `https://api.thebrief.ai/v1/brandkits/assets/folders`\ **Body:** * `brandkitId` (integer, **required**): The id of the brand kit. * `name` (string, **required**): The folder display name. * `parentId` (integer, optional): The parent folder id. Omit to create at the root level. {% code overflow="wrap" %} ``` curl --location 'https://api.thebrief.ai/v1/brandkits/assets/folders' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJ...' \ --data '{ "brandkitId": 123456, "name": "Product photos" }' ``` {% endcode %} #### Response The response will be in JSON format with the following schema: {% code overflow="wrap" %} ```json { "response": { "id": 100, "name": "Product photos", "parentId": null } } ``` {% endcode %} *** ### Rename a brand kit asset folder This endpoint makes an HTTP PUT request to rename an asset folder in a brand kit. #### Request **Method:** PUT\ **Endpoint:** `https://api.thebrief.ai/v1/brandkits/assets/folders`\ **Body:** * `brandkitId` (integer, **required**): The id of the brand kit. * `folderId` (integer, **required**): The id of the folder to rename. * `name` (string, **required**): The new folder name. {% code overflow="wrap" %} ``` curl --location --request PUT 'https://api.thebrief.ai/v1/brandkits/assets/folders' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJ...' \ --data '{ "brandkitId": 123456, "folderId": 100, "name": "Hero images" }' ``` {% endcode %} #### Response The response will be in JSON format with the following schema: {% code overflow="wrap" %} ```json { "response": { "id": 100, "name": "Hero images", "parentId": null } } ``` {% endcode %} *** ### Delete a brand kit asset folder This endpoint makes an HTTP DELETE request to delete an asset folder from a brand kit. #### Request **Method:** DELETE\ **Endpoint:** `https://api.thebrief.ai/v1/brandkits/assets/folders`\ **Body:** * `brandkitId` (integer, **required**): The id of the brand kit. * `folderId` (integer, **required**): The id of the folder to delete. {% code overflow="wrap" %} ``` curl --location --request DELETE 'https://api.thebrief.ai/v1/brandkits/assets/folders' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJ...' \ --data '{ "brandkitId": 123456, "folderId": 100 }' ``` {% endcode %} #### Response The response will be in JSON format with the following schema: {% code overflow="wrap" %} ```json { "response": { "success": true } } ``` {% endcode %} *** # Brand kit media folders ## Brand kit media folders This endpoint makes an HTTP GET request to list brand kit's media folders. ### Request * Method: GET * Endpoint: `https://api.thebrief.ai/v1/brandkit/mediaFolders` * Query Parameters: * `brandkitId` (integer, required): The id of the brand kit. * `parentId`(integer, optional): The parentId of the media folders. ``` curl --location 'https://api.thebrief.ai/v1/brandkit/mediaFolders' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJ...' \ --data '{ "brandkitId": 123456, "parentId:" 65765, }' ``` ### Response The response will be in JSON format with the following schema: ```json { "response": [ { "id": 123, "name": "Assets folder 1" }, { "id": 1234, "name": "Assets folder 2" }, ] } ``` # Brand templates ## List brand templates List all brand templates you have access to with the user assigned to the credentials. This endpoint makes an HTTP GET request to retrieve a list of brand templates from the specified API endpoint. ### **Request** * Method: GET * Endpoint: `https://api.thebrief.ai/v1/brandkits/templates` * Query Parameters: * `keyword` (string, optional): The keyword to search for a brand template name * `brandkitId` (integer, optional): Return only brand templates from a specific brandkit * `folderId` (integer, optional): Return only brand templates from a specific folder * `limit` (integer, optional): The maximum number of brand templates to be returned. * `cursor` (string, optional): A cursor for pagination. * `apiGenerated` (boolean, optional): Return only brand templates generated by API (excluded without this true) * `exactSearch` (boolean, optional): If true, it will return only the brand templates with the name equal to the keyword. (For ex. keyword = 'Brand Template 1' will return only designs with the name 'Brand Template 1') * `orderBy` (enum, optional): option to order the response results by the next fields: ```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": "Brandkit Name", "projectId": 826801, "folderId": 1252444, "apiGenerated": false, "thumbUrl": "Thumbnail URL" } ], "pageInfo": { "hasNextPage": true, "endCursor": "eyJsaW1pdCI6NTAsImxhc3RJZCI6MzEzNDI0Mn0=" } } } ``` The thumbUrl is valid for 12 hours, after which it must be rerun the query to regenerate it. # Brand template folders ### List brand template folders This endpoint makes an HTTP GET request to retrieve the brand template folders of a brand kit. #### Request **Method:** GET\ **Endpoint:** `https://api.thebrief.ai/v1/brandkits/templates/folders`\ **Query parameters:** * `brandkitId` (integer, **required**): The id of the brand kit. * `parentId` (integer, optional): Optional filter by parent folder. {% code overflow="wrap" %} ``` curl --location 'https://api.thebrief.ai/v1/brandkits/templates/folders?brandkitId=123456' \ --header 'Authorization: Bearer eyJ...' ``` {% endcode %} #### Response The response will be in JSON format with the following schema: {% code overflow="wrap" %} ```json { "response": [ { "id": 200, "name": "Summer campaign", "parentId": null } ] } ``` {% endcode %} *** ### Create a brand template folder This endpoint makes an HTTP POST request to create a new brand template folder in a brand kit. #### Request **Method:** POST\ **Endpoint:** `https://api.thebrief.ai/v1/brandkits/templates/folders`\ **Body:** * `brandkitId` (integer, **required**): The id of the brand kit. * `name` (string, **required**): The folder display name. {% code overflow="wrap" %} ``` curl --location 'https://api.thebrief.ai/v1/brandkits/templates/folders' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJ...' \ --data '{ "brandkitId": 123456, "name": "Summer campaign" }' ``` {% endcode %} #### Response The response will be in JSON format with the following schema: {% code overflow="wrap" %} ```json { "response": { "id": 200, "name": "Summer campaign", "parentId": null } } ``` {% endcode %} *** ### Rename a brand template folder This endpoint makes an HTTP PUT request to rename a brand template folder in a brand kit. #### Request **Method:** PUT\ **Endpoint:** `https://api.thebrief.ai/v1/brandkits/templates/folders`\ **Body:** * `brandkitId` (integer, **required**): The id of the brand kit. * `folderId` (integer, **required**): The id of the folder to rename. * `name` (string, **required**): The new folder name. {% code overflow="wrap" %} ``` curl --location --request PUT 'https://api.thebrief.ai/v1/brandkits/templates/folders' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJ...' \ --data '{ "brandkitId": 123456, "folderId": 200, "name": "Winter campaign" }' ``` {% endcode %} #### Response The response will be in JSON format with the following schema: {% code overflow="wrap" %} ```json { "response": { "id": 200, "name": "Winter campaign", "parentId": null } } ``` {% endcode %} *** ### Delete a brand template folder This endpoint makes an HTTP DELETE request to delete a brand template folder from a brand kit. #### Request **Method:** DELETE\ **Endpoint:** `https://api.thebrief.ai/v1/brandkits/templates/folders`\ **Body:** * `brandkitId` (integer, **required**): The id of the brand kit. * `folderId` (integer, **required**): The id of the folder to delete. {% code overflow="wrap" %} ``` curl --location --request DELETE 'https://api.thebrief.ai/v1/brandkits/templates/folders' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJ...' \ --data '{ "brandkitId": 123456, "folderId": 200 }' ``` {% endcode %} #### Response The response will be in JSON format with the following schema: {% code overflow="wrap" %} ```json { "response": { "success": true } } ``` {% endcode %} *** # Ad Networks This endpoint makes an HTTP GET request to retrieve a list of ad networks from the specified API endpoint. The request does not include a request body as it is a GET request. This endpoint is ***deprecated***, please use [List Ad Networks for Ad Serving](#list-a-d-networks-for-ad-serving) or [List Ad Networks for HTML](#list-a-d-networks-for-html) instead. ### Request * Method: GET * Endpoint: `https://api.thebrief.ai/v1/adnetworks` ```bash curl --location 'ttps://api.thebrief.ai/v1/adnetworks' \ --header 'Authorization: Bearer eyJ...' ``` ### Response The response to the request is in JSON format with a status code of 200 (OK). The response body contains an array of ad network objects, each including an ID, name, type, adTag, HTML5, and status properties. ```json { "response": [ { "id": 0, "name": "", "type": "", "adTag": true, "html5": true, "status": true } ] } ``` ## List Ad Networks for Ad Serving This endpoint requests an HTTP **GET** to retrieve a list of ad networks available for ad serving. ### Request * Method: `GET` * Endpoint: `https://api.thebrief.ai/v1/adnetworks/forAdserving` * Query Parameters: This endpoint does not require any query parameters. ```bash curl --location 'https://api.thebrief.ai/v1/adnetworks/forAdserving' \ --header 'Authorization: Bearer ' ``` ### Response Upon a successful execution, the response will have a status code of 200 and a JSON content type. The response body will contain the following structure: JSON {% code overflow="wrap" fullWidth="false" %} ```json { "response": [ { "id": 64, "name": "AdButler", "type": "ADBUTLER", "adTag": true, "html5": false, "status": true, "adNetworkTeams": [] }, { "id": 57, "name": "Adform", "type": "ADFORM", "adTag": true, "html5": true, "status": true, "adNetworkTeams": [] } ] } ``` {% endcode %} Each object in the `response` array represents an ad network and contains the following fields: | Field | Type | Description | | ---------------------------- | ------- | ------------------------------------------------------------------------- | | `id` | Number | Unique identifier of the ad network. | | `name` | String | Name of the ad network. | | `type` | String | Type of the ad network. | | `adTag` | Boolean | Indicates whether an ad tag is available. (Always true for this endpoint) | | `html5` | Boolean | Indicates whether HTML5 ads are supported. | | `status` | Boolean | Status of the ad network (e.g., active/inactive). | | `adNetworkTeams` | Object | Team-related details for the ad network. | | `adNetworkTeams.teamId` | Number | ID of the team associated with the ad network. | | `adNetworkTeams.adNetworkId` | Number | ID of the ad network linked to the team. | | `adNetworkTeams.status` | Boolean | Status of the ad network within the team. | ## List Ad Networks for HTML This endpoint requests an HTTP **GET** to retrieve a list of ad networks available for HTML ### Request * Method: `GET` * Endpoint: `https://api.thebrief.ai/v1/adnetworks/forHtml` * Query Parameters: This endpoint does not require any query parameters. ```bash curl --location 'https://api.thebrief.ai/v1/adnetworks/forHtml' \ --header 'Authorization: Bearer ' ``` ### Response Upon a successful execution, the response will have a status code of 200 and a JSON content type. The response body will contain the following structure: JSON ``` { "response": [ { "id": 1193, "name": "6Sense", "type": "6SENSE", "adTag": false, "html5": true, "status": true, "adNetworkTeams": [] } ] } ``` Each object in the `response` array represents an ad network and contains the following fields: | Field | Type | Description | | ---------------------------- | ------- | -------------------------------------------------------------------------- | | `id` | Number | Unique identifier of the ad network. | | `name` | String | Name of the ad network. | | `type` | String | Type of the ad network. | | `adTag` | Boolean | Indicates whether an ad tag is available. | | `html5` | Boolean | Indicates whether HTML5 ads are supported. (Always true for this endpoint) | | `status` | Boolean | Status of the ad network (e.g., active/inactive). | | `adNetworkTeams` | Object | Team-related details for the ad network. | | `adNetworkTeams.teamId` | Number | ID of the team associated with the ad network. | | `adNetworkTeams.adNetworkId` | Number | ID of the ad network linked to the team. | | `adNetworkTeams.status` | Boolean | Status of the ad network within the team. | # Ad Serving This page contains a documentation for each API related to Ad Serving ## List Ad Networks for Ad Serving If you want to list Ad Networks for Ad Serving, please refer to this [page](/public-api/rest-api/ad-networks#list-a-d-networks-for-ad-serving) ## Enable Ad Tag This endpoint requests an HTTP **POST** to enable Ad Tag for a specific design ### Request * Method: `POST` * Endpoint: `https://api.thebrief.ai/v1/adServing/{{design_hash}}` ```bash curl --location --request POST 'https://api.thebrief.ai/v1/adnetworks/{{design_hash}}' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' ``` ### Response Upon a successful execution, the response will have a status code of 200 and a JSON content type. The response body will contain the following structure: JSON ```json { "response": true } ``` ### Notes * You need to provide a valid design hash to this API in order to enable its Ad Tag. * We only support Ad Tag for designs, not templates. * You can't enable Ad Tag for a design that has already enabled. In this case, an error will be thrown. ## Disable Ad Tag This endpoint requests an HTTP **DELETE** to disable Ad Tag for a specific design ### Request * Method: `DELETE` * Endpoint: `https://api.thebrief.ai/v1/adServing/{{design_hash}}` ```bash curl --location --request DELETE 'https://api.thebrief.ai/v1/adnetworks/{{design_hash}}' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' ``` ### Response Upon a successful execution, the response will have a status code of 200 and a JSON content type. The response body will contain the following structure: JSON ```json { "response": true } ``` ### Notes * You need to provide a valid design hash to this API in order to disable its Ad Tag. * We only support Ad Tag for designs not templates. * You must have an enabled Ad Tag for this design before calling this endpoint, otherwise, an error will be thrown. ## Update Ad Tag Settings This endpoint makes an HTTP **POST** request to update the settings for an AdTag. ### Request * Method: `POST` * Endpoint: `https://api.thebrief.ai/v1/adServing/{{design_hash}}/update-settings` ```bash curl --location --request POST 'https://api.thebrief.ai/v1/adServing/{{design_hash}}/update-settings' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "useAsClickTag": true, "url": "www.google.com", "target": "_blank", "responsiveScaling": false, "networkIds": [1024, 9, 64] }' ``` ### Request Body The request body must be sent in JSON format and include the following parameters: | Parameter | Type | Description | | ----------------- | ---------------- | ---------------------------------------------- | | useAsClickTag | Boolean | Enables/disables click tag functionality | | url | String | URL associated with the AdTag | | target | String | Target window for the AdTag (`_blank`, `_top`) | | responsiveScaling | Boolean | Enables/disables responsive scaling | | networkIds | Array of Numbers | List of ad network IDs to associate | #### Notes * You don't need to pass all the request body's parameters. for example, the following body is valid ```json { "target": "_blank", "useAsClickTag": true, "networkIds": [9, 64, 1024] } ``` ### Response Upon a successful execution, the response will have a status code of `200` and a JSON content type. The response body will contain the following structure: JSON ```json { "response": { "useAsClickTag": true, "url": "www.google.com", "target": "_blank", "responsiveScaling": false, "networkIds": [1024, 9, 64] } } ``` ### Response Fields | Field | Type | Description | | ----------------- | ---------------- | -------------------------------------------------- | | useAsClickTag | Boolean | Indicates if the click tag is enabled | | url | String | The URL configured for the AdTag | | target | String | The target window for the AdTag (`_blank`, `_top`) | | responsiveScaling | Boolean | Indicates if responsive scaling is enabled | | networkIds | Array of Numbers | List of ad network IDs linked to the AdTag | ## Generate Ad Tag Code This endpoint makes an HTTP **GET** request to generate the embed code for an Ad Tag. ### Request * Method: `GET` * Endpoint: `https://api.thebrief.ai/v1/adServing/{{design_hash}}/generate-code` ```bash curl --location 'https://api.thebrief.ai/v1/adServing/{{design_hash}}/generate-code' \ --header 'Authorization: Bearer ' ``` ### Response Upon a successful execution, the response will have a status code of `200` and a JSON content type. #### **Response Body Example:** ```json { "response": { "code": "\n\n\n" } } ``` #### Notes: * You may encounter an error if you update the settings and then directly call this endpoint. The error will be like this ```json { "error": "Internal Server Error:One of AdTags is still syncing, try again later" } ``` In this case, you need to wait a few seconds until all Ad Tags are synced, and then you can generate the Ad Tag code. ## Generate Ad Tag File This endpoint makes an HTTP **POST** request to generate a file containing AdTag data in either **XLSX** or **CSV** format. The response provides a URL to download the generated file. ### Request * Method: `POST` * Endpoint: `https://api.thebrief.ai/v1/adServing/{{design_hash}}/generate-file?format=XLSX` **cURL Example (Generating XLSX File):** ```sh shCopyEditcurl --location --request POST 'https://api.thebrief.ai/v1/adServing/{{design_hash}}/generate-file?format=XLSX' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' ``` **cURL Example (Generating CSV File):** ```sh shCopyEditcurl --location --request POST 'https://api.thebrief.ai/v1/adServing/{{design_hash}}/generate-file?format=CSV' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' ``` ### Response Upon a successful execution, the response will have a status code of `200` and a JSON content type. #### **Response Body Example:** ```json { "response": { "url": "https://creatopy-tmp-d057319.s3.eu-central-1.amazonaws.com/adtags/1743002260957_output.xlsx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASCU4ALRBO32YWP44%2F20250326%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20250326T151741Z&X-Amz-Expires=3600&X-Amz-Signature=98632af260b6b6380903555bec0e6c90bf07e4a93cc14ecc359646fc3b3ae48a&X-Amz-SignedHeaders=host" } } ``` #### **Notes:** * The file format is determined by the `format` query parameter (`XLSX` or `CSV`). * The `url` returned is a temporary link with a time-limited expiration. * The generated file contains Ad Tag data in the specified format. ## Ad Serving Reports This endpoint requests an HTTP **POST** to generate ad serving report (JSON format) ### Request * Method: `POST` * Endpoint: `https://api.thebrief.ai/v1/adServing/report` ```bash curl -X POST https://api.thebrief.ai/v1/adServing/report \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TOKEN" \ -d '{ "from": "2024-01-01", "to": "2026-04-09", "breakdowns": ["design"], "projects": [], "networks": [] }' ``` ### Request Body The request body must be sent in JSON format and include the following parameters: | Parameter | Type | Description | | ---------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | from | String (required) | Start date, YYYY-MM-DD | | to | String (required) | End date, YYYY-MM-DD | | breakdowns | Array of Strings |

project, design, network, design\_size, feed\_variation date\_daily, date\_monthly.

(date\_daily, date\_monthly cannot be used together )

| | projects | Array of Numbers | Filter by project IDs | | networks | Array of Numbers | Filter by network IDs | ### Response Upon a successful execution, the response will have a status code of 200 and a JSON content type. The response body contains the following structure depanding on body params: JSON Example ```json { "response": [ { "views": 1000, "clicks": 50, "ctr": 5.0, "projectId": 1586890, "projectName": "My Project", "designHash": "abc123", "designName": "Banner Ad", "designSize": "Medium (300x250 px)", "networkId": 1, "networkName": "Google Ads", "date": "Tue Apr 01 2026", "month": "04/2026", "feedVariation": "variant-a" } ] } ``` # Users ## List team users This endpoint makes an HTTP GET request to retrieve a list of users from the team. **Request Body:** This request does not require a request body. ### Request * Method: GET * Endpoint: `https://api.thebrief.ai/v1/users` * Query Parameters: * `keyword` (string, optional): The keyword to search for users (it will search in name and email too). * `limit` (integer, optional): The maximum number of users to be returned. * `cursor` (string, optional): A cursor for pagination. * `orderBy` (enum, optional): option to order the response results by next fields: ```typescript ID NAME CREATED_AT UPDATED_AT ``` * `orderDirection` (enum, optional): option to order the response by direction: ``` ASC DESC ``` ```bash curl --location 'https://api.thebrief.ai/v1/users?keyword=userName&limit=10&cursor=eyJsaW1pdCI6MSwibGFzdElkIjozOTE3M' \ --header 'Authorization: Bearer eyJ...' ``` **Response Body** * `response` (object) * `totalCount` (number): The total count of users. * `nodes` (array): An array of user objects. * `id` (number): The unique identifier of the user. * `name` (string): The name of the user. * `email` (string): The email address of the user. * `role` (object): The role object of the user. * `id` (number): The unique identifier of the role. * `name` (string): The name of the role. * `description` (string): The description of the role. * `profilePicture` (string): The URL of the user's profile picture. * `pageInfo` (object): Information about the page. * `hasNextPage` (boolean): Indicates whether there is a next page. * `endCursor` (string): The cursor for the end of the page. ## Create team user This endpoint allows you to create a new team user. ### Request * Method: POST * Endpoint: `https://api.thebrief.ai/v1/users` * Body: * `name` (string, required): The name of the user. * `email` (string, required): The email of the user. * `role` (string, required): The role of the user. ### Response The response will be in JSON format with the following structure: * `name` (string) - The name of the user. * `id` (int) - The id of the user. * `email` (string) - The email of the user. 
{
    "response": {
        "name": "User Name",
        "id": 1111111,
        "email": "user.email@email.com"
    }
}
## Delete team user This endpoint allows you to delete a team user. ### Request * Method: DEL * Endpoint: `https://api.thebrief.ai/v1/users` * Body: * `email` (string, required): The email of the user. ### Response The response will be in JSON format: ```json { "response": true } ``` ## Update team user role This endpoint allows you to update the role in a team for a team user. ### Request * Method: PUT * Endpoint: `https://api.thebrief.ai/v1/users/updateTeamUserRole` * Body: * `userId` (integer, required): The id of the user. * `roleId` (integer, required): The role id. ### Response The response will be in JSON format with the following structure: * `id` (int) - The id of the user. * `name` (string) - The name of the user. * `email` (string) - The email of the user. * `profilePicture` (string) - The profilePicture url of the user. * `role` (object) - The role of the user in the team. * `id` (int) - the id of the role * `name` (string) - the name of the role * `description` (string) - the description of the role 
{
    "response": {
        "id": 11111,
        "name": "User Name",
        "email": "user.email@email.com",
        "profilePicture": null,
        "role": {
            "id: 3,
            "name": "Viewer",
            "description": null
        },
    }
}
# Team roles ## List team roles This endpoint makes an HTTP GET request to retrieve a list of team roles. **Request Body** This request does not require a request body. ### Request * Endpoint: `https://api.thebrief.ai/v1/teamRoles` ### Response * Status: 200 * Content-Type: application/json The response will contain an array of team roles, where each role is represented by an object with "id" and "name" properties. Example response: ``` { "response": [ { "id": 1, "name": "Admin" }, { "id": 2, "name": "Viewer" } ] } ``` # Webhooks ## List team webhooks This endpoint makes an HTTP GET request to retrieve a list of webhooks from the team. **Request Body** This request does not require a request body. ### Request * Method: `GET` * Endpoint: `https://api.thebrief.ai/v1/webhooks` ```bash curl --location 'ttps://api.thebrief.ai/v1/webhooks' \ --header 'Authorization: Bearer eyJ...' ``` **Response Body** * `response` (object) * `id` (number): The webhook id. * `name` (string): The name of the webhook. * `webhookUrl` (string): The URL of the webhook. * `createdAt` (date): webhook creation date. * `createdByUser` (object) * `id` (number): The unique identifier of the user who creates the webhook. * `name` (string): The name of the user who creates the webhook. * actions (array) * `actionId` (number): The action ID was added to the webhook. * `createdAt` (Date): The date * `createdByUser` (object) * `id` (number): The id of the user who added the action to the webhook. * `name` (string): The user's name who added the action to the webhook. * `action` (object) * `name`: the added action name. * `description`: the added action description
## Create team webhook This endpoint allows you to create a new team webhook. ### Request * Method: `POST` * Endpoint: `https://api.thebrief.ai/v1/webhooks` * Body: * `name` (string, required): The name of the webhook. * `url` (string, required): The URL of the webhook. * `actions` (array, required): The selected actions to add to webhook (for. ex: \[1, 5]) ### Response The response will be in JSON format with the following structure: * `name` (string) - The name of the webhook. * `id` (int) - The id of the webhook. * `webhookUrl` (string) - The URL of the webhook. * `actions` (array) * `actionId` (number) - the id of the action * `createdAt` (date) - the date when action was added to the webhook * `createdByUser` (object) * `id` (number) - the user's ID who added the action to the webhook * `name` (string) - the user's name who added the action to the webhook * `action` (object) * `id` (number) - the action ID added to the webhook * `name` (string) - the name of the action added to the webhook * `description` (string) - the description of the action added to the webhook * `config` (string) - some config of the action added to the webhook * `createdAt` (Date) - the date when the action was created * `createdAt` (Date) - the date when the webhook was created * `createdByUser` (object) * `id` (number) - the ID of the user who created the webhook * `name` (string) - the name of the user who created the webhook ```json { "response": { "name": "Webhook name", "id": 1111111, "webhookUrl": "https://webhookurl.webhook.com", "actions": [ { "actionId": 12, "createdAt": "2024-10-03T08:36:56.978Z", "createdByUser": { "id": 12345, "name": "User name" } "action" { "id": 1, "name": "comment/create", "description": " Comment created", "config": null, "createdAt": "2024-10-03T08:36:56.978Z" } } ... ] "createdAt": "2024-10-03T08:36:56.978Z", "createdByUser": { "id": 12345, "name": "User name" } } } ``` ## Delete team webhook This endpoint allows you to delete a team webhook. ### Request * Method: `DELETE` * Endpoint: `https://api.thebrief.ai/v1/webhooks` * Body: * `webhookId` (integer, required): The id of the team webhook. ### Response The response will be in JSON format: ```json { "response": true } ``` ## Update team webhook This endpoint allows you to update an existing team webhook. ### Request * Method: `PUT` * Endpoint: `https://api.thebrief.ai/v1/webhooks` * Body: * `webhookId` (integer, required): The webhook id * `name` (string, optional): The new name of the webhook. * `url` (string, optional): The new URL of the webhook. * `actions` (array, optional): The newly selected actions to add to webhook (for. ex: \[1, 2, 4]) ### Response The response will be in JSON format with the following structure: * `name` (string) - The name of the webhook. * `id` (int) - The id of the webhook. * `webhookUrl` (string) - The URL of the webhook. * `actions` (array) * `actionId` (number) - the id of the action * `createdAt` (date) - the date when action was added to the webhook * `createdByUser` (object) * `id` (number) - the user's ID who added the action to the webhook * `name` (string) - the user's name who added the action to the webhook * `action` (object) * `id` (number) - the action ID added to the webhook * `name` (string) - the name of the action added to the webhook * `description` (string) - the description of the action added to the webhook * `config` (string) - some config of the action added to the webhook * `createdAt` (Date) - the date when the action was created * `createdAt` (Date) - the date when the webhook was created * `createdByUser` (object) * `id` (number) - the ID of the user who created the webhook * `name` (string) - the name of the user who created the webhook # Webhook action types ## List webhook action types This endpoint makes an HTTP GET request to retrieve a list of action types to which will send an event to webhookt. **Request Body** This request does not require a request body. ### Request * Endpoint: `https://api.thebrief.ai/v1/webhookActions` ### Response * Status: 200 * Content-Type: application/json The response will contain an array of webhook action, where each action is represented by an object with "id", "name", "description", "config" and "createdAt" properties. Example response: ``` { "response": [ { "id": 1, "name": "comment/create", "description": "Comment created", "config": null, "createdAt": "2024-09-12T17:57:23:4242 }, { "id": 5, "name": "session/finish", "description": "Session finished", "config": null, "createdAt": "2024-09-19T16:17:29.4512" } ] } ``` # Design Versions ## List design versions This endpoint makes an HTTP GET request to retrieve a list of design versions ### Request * Method: GET * Endpoint: `https://api.thebrief.ai/v1/designVersion` * Query Parameters: * `hash` (string, required): The hash of the design. **Response Body** * `response` (array) * `id` (string): The version id. * `lastModified` (date): The last modification date of the design. * `lastModifiedByName` (string): The user's name who made the last modifications to the design. * `lastModifiedByProfilePicture` (string): The user's profilePicture who made the last modifications to the design. * `versionName` (string): The name of the version. * `sizeHash` (string): The size's hash from the set ```json { "response": [ { "id": "w8Tz8D_sdUs1dr1PxyB6CoeG8pllRLFF", "lastModified": "2024-11-13T08:18:29.000Z", "lastModifiedByName": "User name", "lastModifiedByProfilePicture": "", "versionName": "", "sizeHash": "gry44d" }, { "id": "pY3_mntBqded4dvBwOyT9uSYXmNyfw4q", "lastModified": "2024-11-13T08:09:09.000Z", "lastModifiedByName": "User Name", "lastModifiedByProfilePicture": "", "versionName": "", "sizeHash": "uhuh7" }, ] } ``` ## Create a new design version This endpoint allows you to create a new version for a design. ### Request * Method: `POST` * Endpoint: `https://api.thebrief.ai/v1/designVersion` * Body: * `hash` (string, required): The hash of the design. * `versionName` (string, required): The new version's name. ### Response The response will be in JSON format with the following structure: * `response` (object) * `status` (enum) - (succes, failed) ```json { "response": { "status": "success" } } ``` ## Update version name This endpoint allows you to update a version's name. ### Request * Method: `PUT` * Endpoint: `https://api.thebrief.ai/v1/designVersion` * Body: * `hash` (string, required): The hash of the design. * `versionName` (string, required): The new name of the design version. * `versionId` (string, required): The versionId of the design version. ### Response The response will be in JSON format: ```json { "response": { "status": "success" } } ``` ## Restore a design version This endpoint allows you to restore a version of a design. ### Request * Method: `POST` * Endpoint: `https://api.thebrief.ai/v1/designVersion/restore` * Body: * `hash` (string, required): The hash of the design * `versionId` (string, required): The versionId of the version. ### Response The response will be in JSON format: ```json { "response": { "status": "success" } } ``` # Folders ## List folders This endpoint makes an HTTP GET request to retrieve a list of projects from a level of a folder's tree. ### Request * Method: GET * Endpoint: `https://api.thebrief.ai/v1/folders` * Query Parameters: * `projectId` (integer, required): The projectId in which will search the folders * `parentId`(integer, optional): Will search subfolders in folder with id equal to parentId value ```bash curl --location 'https://api.thebrief.ai/v1/folders' \ --header 'Authorization: Bearer eyJh...' ``` ### Response Upon a successful execution, the response will have a status code of 200 and a JSON content type. The response body will contain the following structure: JSON ```json { "response": { "folders": [ { "id": 111111, "name": "Folder Name 1", "parentId": null, "createdByUser": { "id": 22222, "name": "User Name 1" }, "isParent": null, "updatedAt": "2024-12-04T08:59:00.509Z", "createdAt": "2024-09-30T07:11:45.948Z", "updatedByUser": { "id": 33333, "name": "User name 2" } }, { "id": 333333, "name": "Folder Name 2", "parentId": null, "createdByUser": { "id": 44444, "name": "User Name 3" }, "isParent": null, "updatedAt": "2024-12-03T15:21:53.010Z", "createdAt": "2024-12-03T14:38:17.513Z", "updatedByUser": { "id": 44444, "name": "User Name 4" } }, "path": [], "rootFolderHash": null } } ``` If the parentId is not null in the request the JSON response will contain data about the path to that folder ```json { "response": { "folders": [ { "id": 111111, "name": "Folder Second Level, "parentId": 222222, "createdByUser": { "id": 111111, "name": "User Name 1" }, "isParent": null, "updatedAt": "2024-11-15T12:10:29.480Z", "createdAt": "2024-11-13T13:51:19.973Z", "updatedByUser": { "id": 22222, "name": "User Name 2" } } ], "path": [ { "name": "Main Level Folder", "id": 333333, "shared": false, "publicStatus": "public", "publicHash": "dgnop4kkelmj", "template": false } ], "rootFolderHash": null } } ``` ## Create Folder This endpoint allows you to create a new folder. ### Request * Method: POST * Endpoint: `https://api.thebrief.ai/v1/folders` * Body: * `name` (string, required): The name of the folder. * `projectId` (integer, required): The ID of the project in which user will create the folder. * `parentId` (integer, optional): The ID of the folder in within the user will create the new folder. ### Response Upon a successful execution, the response will have a status code of 200 and a JSON content type. The response body will contain the following structure: JSON ```json { "response": { "folder": { "id": 111111, "name": "Subfolder 1", "projectId": 358029, "parentId": 717554, "createdByUser": { "id": 111111, "name": "User Name 1" }, "updatedByUser": { "id": 111111, "name": "User Name 1" }, "createdAt": "2024-12-04T18:21:54.636Z", "updatedAt": "2024-12-04T18:21:54.636Z", "isParent": null } } } ``` ## Delete Folder This endpoint allows you to delete a folder. ### Request * Method: DELETE * Endpoint: `https://api.thebrief.ai/v1/folders` * Body: * `folderId` (integer, required): The ID of the folder you want to be deleted. {% code title="Request example" %} ```bash curl --location --request DELETE 'https://api.thebrief.ai/v1/folders' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJhdXRob3JpemF0aW9uIjoiQmVhcmVyIGV5SmhiR2NpT2lKSVV6STFOaUlzSW5SNWNDSTZJa3BYVkNKOS5leUpwWVhRaU9qRTJPREV4TVRVMU56YzVPRElzSW1Oc2FXVnVkRWxrSWpvaU16QmpaalJsTldRdE1XRmxOQzAwT1RrNExUa3lNV010TVdVMU5qZzJOemd4WW1VeEluMC56WlRDX0ZHZW5FdklRZHhZTlk1cW9OWnlxSEdEOUYtTUtpNm1uV0h6V1NvIiwiYWxnIjoiSFMyNTYifQ.eyJjbGllbnRJZCI6IjZhMzhlYTk3LTEyOWQtNDE3MS04NTljLTU1MzVjOWYzZTRlMSJ9.gWvLWJSqk0bSO78t5xxdYcR08KHAyvQtKCxd0mnlK5U' \ --data '{ "folderId": 123456 }' ``` {% endcode %} ### Response ``` { "response": { "status": "success" } } ``` ## Update Folder This endpoint allows you to update a folder's name. ### Request * Method: PUT * Endpoint: `https://api.thebrief.ai/v1/folders` * Body: * `name` (string, required): The new name of the folder you want to update. * `folderId` (integer, required): The ID of the folder you want to be updated. {% code title="Request example" %} ```bash curl --location --request PUT 'https://api.thebrief.ai/v1/folders' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJhdXRob3JpemF0aW9uIjoiQmVhcmVyIGV5SmhiR2NpT2lKSVV6STFOaUlzSW5SNWNDSTZJa3BYVkNKOS5leUpwWVhRaU9qRTJPREV4TVRVMU56YzVPRElzSW1Oc2FXVnVkRWxrSWpvaU16QmpaalJsTldRdE1XRmxOQzAwT1RrNExUa3lNV010TVdVMU5qZzJOemd4WW1VeEluMC56WlRDX0ZHZW5FdklRZHhZTlk1cW9OWnlxSEdEOUYtTUtpNm1uV0h6V1NvIiwiYWxnIjoiSFMyNTYifQ.eyJjbGllbnRJZCI6IjZhMzhlYTk3LTEyOWQtNDE3MS04NTljLTU1MzVjOWYzZTRlMSJ9.gWvLWJSqk0bSO78t5xxdYcR08KHAyvQtKCxd0mnlK5U' \ --data '{ "name": "New folder name" "folderId": 123456 }' ``` {% endcode %} ### Response ``` { "response": { "folder": { "id": 123456, "name": "New folder name", "projectId": 567890, "parentId": null, "createdByUser": { "id": 111111, "name": "User Name 1" }, "updatedByUser": { "id": 111111, "name": "User Name 1" }, "createdAt": "2024-12-03T14:38:17.513Z", "updatedAt": "2024-12-03T15:21:53.010Z", "isParent": null } } } ``` # Move design to folder This endpoint is used to move a design to a specific folder. ### Request * Method: POST * Endpoint: `https://api.thebrief.ai/v1/moveDesignToFolder` * Body: * `designHash` (string, required): The hash of the design to be moved. * `folderId` (integer, required): The ID of the folder to which the design will be moved. If you want to move on to the root of the project `folderId`should be `-1`. ```bash curl --location 'https://api.thebrief.ai/v1/moveDesignToFolder' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJhdXUpI2Yi5h4...' \ --data '{ "designHash": "mz2k0q", "folderId": 716578 }' ``` ### Response Upon successful execution, the response will have a status code of 200 and a JSON content type. The response body will contain the following structure: JSON ```json { "response": true } ``` # Error codes We are using the following error codes for our endpoints: * 400: Invalid user inputs or broken design. * 401: Unauthenticated user request. * 403: Forbidden access to a resource. * 404: Resource not found. * 405: Method not allowed. * 410: User lacks access to a resource. * 429: Too many requests. * 500: Internal server error for unhandled errors. Our aim is to reduce 500 errors through ongoing improvements in error management. # Designs ## List only designs (not templates) 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: ```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. # Design Fonts ## List fonts which can be used with a design(template) List all fonts which can be used to on a design (template). This endpoint makes an HTTP GET request to retrieve a list of fonts from the specified API endpoint. ### **Request** * Method: GET * Endpoint: `https://api.thebrief.ai/v1/designFonts` * Query Parameters: * `templateHash` (string, required): The hash of the design(template). ### 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 objects with "fontName" and array of "variants" properties,. Request example: ``` { "response": [ { "fontName": "ABeeZee", "variants": [ { "weight": "400", "subFamily": "Regular" }, { "weight": "400italic", "subFamily": "Regular Italic" } ] }, { "fontName": "Abel", "variants": [ { "weight": "400", "subFamily": "Regular" } ] }, { "fontName": "Abril Fatface", "variants": [ { "weight": "400", "subFamily": "Regular" } ] } ] } ``` These fontName values should be used with export-with-changes endpoint for FONTFAMILY attribute. # Credits ### Important Notice **All Credits endpoints are not compatible with legacy plans.** Requests from teams with this legacy plan version will receive a 400 error response ```json { "error": "This endpoint is not available for teams that have a legacy plan" } ``` ### Get Subscription Info This endpoint makes an HTTP GET request to retrieve comprehensive subscription information for a team, including credit balance, addons, and subscription details. #### Request * Method: GET * Endpoint: `https://api.thebrief.ai/v1/credits/subscription-info` * Query Parameters: * `teamId` (integer, required): The ID of the team to retrieve subscription information for. ```bash curl --location 'https://api.thebrief.ai/v1/credits/subscription-info?teamId=12345' \ --header 'Authorization: Bearer eyJh...' ``` #### Response Upon a successful execution, the response will have a status code of 200 and a JSON content type. The response body will contain the following structure: ```json { "response": { "id": 0, "planCode": "", "planVersion": "", "currentPeriodStartedAt": "", "currentPeriodEndsAt": "", "addons": [ { "id": 0, "code": "", "name": "", "type": "", "quantity": 0, "unitAmountInCents": 0, "createdAt": "", "updatedAt": "" } ], "creditBalance": { "availableRecurringCredits": 0, "availableRollingCredits": 0, "availableTopUpCredits": 0, "lockedRecurringCredits": 0, "lockedRollingCredits": 0, "lockedTopUpCredits": 0, "totalAvailableCredits": 0, "totalLockedCredits": 0, "consumedRecurringCredits": 0, "consumedRollingCredits": 0, "consumedTopUpCredits": 0, "totalConsumedCredits": 0, "dailyConsumedCredits": 0, "creditsLimit": { "recurringCredits": 0, "rollingCredits": 0, "topUpCredits": 0 } } } } ``` **Response Fields:** * `id`: The subscription ID * `planCode`: The current plan code (e.g., "pro\_monthly", "enterprise\_yearly") * `planVersion`: The version of the plan * `currentPeriodStartedAt`: ISO 8601 timestamp when the current billing period started * `currentPeriodEndsAt`: ISO 8601 timestamp when the current billing period ends * `addons`: Array of subscription addons * `id`: Addon ID * `code`: Addon code * `name`: Human-readable addon name * `type`: Addon type (e.g., "recurring", "one\_time") * `quantity`: Quantity of the addon * `unitAmountInCents`: Cost per unit in cents * `createdAt`: ISO 8601 timestamp when addon was created * `updatedAt`: ISO 8601 timestamp when addon was last updated * `creditBalance`: Detailed breakdown of credit balance * `availableRecurringCredits`: Available credits from recurring subscription * `availableRollingCredits`: Available credits that roll over * `availableTopUpCredits`: Available credits from top-up purchases * `lockedRecurringCredits`: Locked recurring credits (reserved for ongoing operations) * `lockedRollingCredits`: Locked rolling credits * `lockedTopUpCredits`: Locked top-up credits * `totalAvailableCredits`: Sum of all available credits * `totalLockedCredits`: Sum of all locked credits * `consumedRecurringCredits`: Consumed recurring credits in current period * `consumedRollingCredits`: Consumed rolling credits * `consumedTopUpCredits`: Consumed top-up credits * `totalConsumedCredits`: Sum of all consumed credits * `dailyConsumedCredits`: Credits consumed today * `creditsLimit`: Overall credit limits for the subscription **Example Response:** ```json { "response": { "id": 12345, "planCode": "pro_monthly", "planVersion": "v2", "currentPeriodStartedAt": "2024-01-01T00:00:00.000Z", "currentPeriodEndsAt": "2024-02-01T00:00:00.000Z", "addons": [ { "id": 1, "code": "extra_credits", "name": "Extra Credits", "type": "recurring", "quantity": 1000, "unitAmountInCents": 5000, "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2024-01-01T00:00:00.000Z" } ], "creditBalance": { "availableRecurringCredits": 500, "availableRollingCredits": 200, "availableTopUpCredits": 100, "lockedRecurringCredits": 50, "lockedRollingCredits": 20, "lockedTopUpCredits": 10, "totalAvailableCredits": 800, "totalLockedCredits": 80, "consumedRecurringCredits": 450, "consumedRollingCredits": 180, "consumedTopUpCredits": 90, "totalConsumedCredits": 720, "dailyConsumedCredits": 25, "creditsLimit": { "recurringCredits": 1000, "rollingCredits": 500, "topUpCredits": 200 } } } } ``` *** ### Get Team Consumption Report This endpoint makes an HTTP GET request to retrieve a detailed consumption report for a team, including breakdown by users and features for a specified time period. #### Request * Method: GET * Endpoint: `https://api.thebrief.ai/v1/credits/team-consumption-report` * Query Parameters: * `teamId` (integer, required): The ID of the team to retrieve the consumption report for. * `startDate` (string, required): Start date for the report period in ISO 8601 format (e.g., "2024-01-01T00:00:00.000Z") * `endDate` (string, required): End date for the report period in ISO 8601 format (e.g., "2024-12-31T23:59:59.999Z") * `userIds` (string, optional): Comma-separated list of user IDs to filter the report by specific users (e.g., "101,102,103") * `creditOperationIds` (string, optional): Comma-separated list of credit operation IDs to filter by specific operations (e.g., "1,2,3") ```bash curl --location 'https://api.thebrief.ai/v1/credits/team-consumption-report?teamId=12345&startDate=2024-01-01T00:00:00.000Z&endDate=2024-12-31T23:59:59.999Z&userIds=101,102,103' \ --header 'Authorization: Bearer eyJh...' ``` #### Response Upon a successful execution, the response will have a status code of 200 and a JSON content type. The response body will contain the following structure: ```json { "response": { "totalTeamConsumption": 0, "breakdownByUsers": [ { "userId": 0, "totalUserConsumption": 0, "breakdownByFeatures": [ { "featureName": "", "featureType": "", "credits": 0 } ] } ] } } ``` **Response Fields:** * `totalTeamConsumption`: Total credits consumed by the entire team during the specified period * `breakdownByUsers`: Array of consumption data per user * `userId`: The ID of the user * `totalUserConsumption`: Total credits consumed by this user * `breakdownByFeatures`: Array of consumption data per feature for this user * `featureName`: Human-readable name of the feature (e.g., "AI Image Generation", "Design Export") * `featureType`: Type identifier of the feature (e.g., "ai\_generation", "export", "video\_export") * `credits`: Number of credits consumed for this feature **Example Response:** ```json { "response": { "totalTeamConsumption": 1250, "breakdownByUsers": [ { "userId": 101, "totalUserConsumption": 500, "breakdownByFeatures": [ { "featureName": "AI Image Generation", "featureType": "ai_generation", "credits": 300 }, { "featureName": "Design Export", "featureType": "export", "credits": 200 } ] }, { "userId": 102, "totalUserConsumption": 750, "breakdownByFeatures": [ { "featureName": "AI Image Generation", "featureType": "ai_generation", "credits": 450 }, { "featureName": "Video Export", "featureType": "video_export", "credits": 300 } ] } ] } } ``` **Use Cases:** * Analyze team credit consumption over a specific period * Track individual user consumption patterns * Identify which features consume the most credits * Generate billing reports and usage analytics * Monitor credit usage trends for capacity planning *** ### List Credit Operations This endpoint makes an HTTP GET request to retrieve all available credit operations with their associated costs. This is useful for understanding how many credits each feature operation consumes. #### Request * Method: GET * Endpoint: `https://api.thebrief.ai/v1/credits/operations` * Query Parameters: None ```bash curl --location 'https://api.thebrief.ai/v1/credits/operations' \ --header 'Authorization: Bearer eyJh...' ``` #### Response Upon a successful execution, the response will have a status code of 200 and a JSON content type. The response body will contain the following structure: ```json { "response": { "operations": [ { "id": 0, "featureName": "", "featureType": "", "cost": 0 } ] } } ``` **Response Fields:** * `operations`: Array of credit operations * `id`: Unique identifier for the operation * `featureName`: Human-readable name of the feature (e.g., "AI Image Generation", "Design Export") * `featureType`: Type identifier of the feature (e.g., "ai\_generation", "export", "video\_export") * `cost`: Number of credits consumed per operation **Example Response:** ```json { "response": { "operations": [ { "id": 1, "featureName": "AI Image Generation", "featureType": "ai_generation", "cost": 10 }, { "id": 2, "featureName": "Design Export", "featureType": "export", "cost": 5 }, { "id": 3, "featureName": "Video Export", "featureType": "video_export", "cost": 15 }, { "id": 4, "featureName": "AI Text Generation", "featureType": "ai_text", "cost": 8 }, { "id": 5, "featureName": "Background Removal", "featureType": "background_removal", "cost": 12 } ] } } ``` **Use Cases:** * Display credit costs to users before they perform operations * Calculate estimated costs for bulk operations * Build custom pricing calculators * Integrate cost information into your application's UI * Monitor changes in operation costs over time *** ### Authentication All Credits endpoints require authentication using a Bearer token in the Authorization header: ```bash --header 'Authorization: Bearer YOUR_API_TOKEN' ``` To obtain an API token, please refer to the [Authentication](https://docs.thebrief.ai/public-api/authentication) section of the documentation. *** ### Error Responses All endpoints may return the following error responses: #### 400 Bad Request Returned when required parameters are missing or invalid. ```json { "error": "Missing teamId parameter" } ``` ```json { "error": "Invalid teamId parameter" } ``` #### 401 Unauthorized Returned when the authentication token is missing or invalid. ```json { "error": "Unauthorized" } ``` #### 403 Forbidden Returned when the authenticated user doesn't have access to the requested team. ```json { "error": "You don't have access to this team" } ``` #### 500 Internal Server Error Returned when an unexpected error occurs on the server. ```json { "error": "Failed to fetch subscription info" } ``` ```json { "error": "Failed to fetch team consumption report" } ``` ```json { "error": "Failed to fetch credit operations" } ``` *** ### Rate Limiting These endpoints are subject to the standard API rate limits. Please refer to the main API documentation for current rate limit policies. # GraphQL Creatopy exposes a single GraphQL endpoint for you to dynamically query, at `https://graphql.thebrief.ai/public`. To make a request, you'll need to include two things: an authorization token and a GraphQL query or mutation. # Endpoints and queries ### Endpoints and queries All The Brief Public API queries are made on a single GraphQL endpoint, which only accepts POST requests: `https://graphql.thebrief.ai/public` ```shell curl -X POST \ https://graphql.thebrief.ai/public \ -H 'Content-Type: application/graphql' \ -H 'Authorization": Bearer: {authorization_token}' \ } \ -d ' query getDownloadStatus { download(input: { downloadId: "{downloadId}" }) { status creatives { __typename ... on DownloadCreativeDesign { id status url } ... on DownloadCreativeSet { creatives { id status url } } } } } ' ``` # Postman Collection In your The Brief account, under your profile, go to **Manage account** and select **API credentials** section**.** From there you can use existing API key or create an API key that you'll use to communicate with the API: {% embed url="" %} Postman The Brief API Collection {% endembed %} {% embed url="" %} Postman Docs {% endembed %} # App integration You can use the App Integration in order to integrate The Brief editor within your app, allowing you to use the full capabilities & features of our Ad Studio experience. To access this workflow, the integrating client must provide a JWT as an entry point. This token should contain the clientId, userId (for session impersonation), and an action defining what the session will do before redirecting the user to editor mode. All of this must be signed with the secret. The clientId and secret pair are created in The brief under **Manage account/API credentials.** You can generate the token using the NodeJS script: ```javascript // nodejs import jwt from 'jsonwebtoken'; const clientId = 'yourClientId'; // Replace with your actual clientId const secret = 'yourSecret'; // Replace with your secret key // Create the payload const payload = { clientId, userId, action: { type: "create_blank_design", sizes: [{"width": 111, "height": 111}], projectId: 100, folderId: 111, // this is optional editorMode: "adstudio" } }; // Sign the payload to create a JWT const token = jwt.sign(payload, secret); // Construct the URL const url = `https://app.thebrief.ai/tokenAuth?token=${token}`; console.log(url); ``` Or for testing purposes, you can use a JWT playground like the one from , where you can generate the token manually. To start the session, add the generated token in the The Brief app `https://app.thebrief.ai/tokenAuth?token=${token}`

JWT.IO example

The editor can be embedded in an iframe, too. Here's how: [Iframe embedding](/app-integration/iframe-embedding) ## JWT Parameters These are general parameters for starting the JWT token that starts the editor session. > **Parameters for this action:** > > **`clientId`** - (required) The clientId form the API Configuration inside The Brief app (the same that is used to generate bearer token to call APIs requests) > > **`userId`**- (required) the userId for the user you impersonate in the session (if the clientId/secret pair is generated by the team owner or admin, you can impersonate users from your team). > > **`action`**- (required) define the action that this session if started for defined [here](#actions-for-the-session). > > **`sessionConfig`**- usually UI configs for the current session. More on them [here](#session-configuration). ## Actions for the session To start a session, you need to provide an action type. Currently, we support four actions: *create\_design\_from\_template, create\_blank\_design,* *edit\_design*, and *get\_share\_link*. Add the action/type field in the JWT to call these actions. Each action has a set of specific parameters, which are explained for each type below. ```json "action": { "type": "create_design_from_template", } ``` ### Edit design This action will create a new design from an existing one (template). > **Parameters for this action:** > > **`hash`** - The hash of the template (design or custom template) > > **`editorMode`** - Which editor to open in the session ("adStudio" or "light-editor") ```json { "clientId": "YOUR-CLIENT_ID", "userId": userId, "action": { "type": "edit_design", "hash": "template-hash", "editorMode": "adstudio" | "light-editor" } } ``` ### Create a design from a template This action will create a new design from an already existing design (template). > **Parameters for this action:** > > **`hash`** - The hash of the template (design or custom template) > > **`name`** - The name I want the design to have (Optional) > > **`projectId`** - ID of the project in which we want this design to be created > > **`folderId`** - ID of the folder in which we want this design to be created (optional) > > **`editorMode`** - Which editor to open in the session ("adStudio" or "light-editor") ```json { "clientId": "YOUR-CLIENT_ID", "userId": userId, "action": { "type": "create_design_from_template", "name": "My design name", "hash": "template-hash", "projectId": your-project-id, "folderId": your-folder-id, // this is optional "editorMode": "adstudio" | "light-editor" } } ``` ### Create a blank design This action will create a new blank design. > **Parameters for this action:** > > **`sizes`** - An array of sizes for the design > > **`customSizes`** - An array of custom sizes (note: you can only provide either **`sizes`** or **`customSizes`** not both) > > **`name`** - The name I want the design to have (Optional) > > **`projectId`** - ID of the project where the design will be created > > **`folderId`** - ID of the folder where the design will be created (optional) > > **`editorMode`** - Editor to open in the session ("adStudio" only) **An Example using the sizes parameter** ```json { "clientId": "YOUR-CLIENT_ID", "userId": userId, "action": { "type": "create_blank_design", "name": "My design", "sizes": [{"width": 111, "height": 111}], "projectId": your-project-id, "folderId": your-folder-id, // this is optional "editorMode": "adstudio" } } ``` **An Example using the customSizes parameter**
`customSizes` gives you the ability to name your sizes while you're creating your design ``` { "clientId": "YOUR-CLIENT_ID", "userId": userId, "action": { "type": "create_blank_design", "name": "My design", "customSizes": [{"width": 400, "height": 600, "name": "Facebook size"}], "projectId": your-project-id, "folderId": your-folder-id, // this is optional "editorMode": "adstudio" } } ``` ### Get the share link This action will get you the shared link for a design or a folder based on the provided parameters. If you give a `designHash`, you will get a shared link for a design. And, if you give a `folderId`, you will get a shared link for a folder. One of these parameters must be provided.\ This action now supports an optional parameter, `openRightBar`, to provide additional functionality for the share link page. > **Parameters for this action:** > > **`designHash`** - The hash of the design that you want its share link (could be `undefined` if you provide `folderId`) > > **`folderId`** - The id of the folder that you want its share link (could be `undefined` if you provide `designHash`) > > **`openRightBar`**- If `true`, opens the comments panel on the share link page. Has no effect if `useShareLinkComments` in the `sessionConfig` is disabled. (this param is optional and its default value is `false`) ```json { "clientId": "YOUR-CLIENT_ID", "userId": userId, "action": { "type": "get_share_link", "designHash": "design-hash", // mandatory for a design share link "folderId": 1234, // mandatory for a folder share link "openRightBar": true // the useShareLinkComments in the sessionConfig should be enabled to use this param } } ``` #### Behavior of openRightBar Param * If the parameter `openRightBar` is set to `true`: * The comments panel will open automatically when the share link page is accessed, provided that `useShareLinkComments` in the `sessionConfig` is enabled. * If `useShareLinkComments` If this parameter is disabled, this parameter will be ignored, and the comments panel will not be displayed. * When `openRightBar` it is omitted or set to `false`, the comments panel will remain closed by default. ### Flow: Create from URL (BETA) This action will start the flow of creating a design from a URL using AI > **Parameters for this action:** > > **`projectId`** - ID of the project where the design will be created > > **`folderId`** - ID of the folder where the design will be created (optional) > > **`name`** - The name I want the design to have (Optional) > > **`brandkitId`** - Brand Kit ID: Specifies the Brand Kit where assets will be uploaded. In this flow, only assets and templates associated with this Brand Kit will be accessible. (Optional) > > **`redirectURL`** - At the end of the creation flow will be redirecting to this URL (Optional) ```json { "type": "nextgen_flow_create_from_url", "projectId": 100, "folderId": 124, // this param is optional "name": "Test design name", // this param is optional "brandkitId": 124 // this param is optional "redirectUrl": "www.google.com" // this param is optional } ``` ### Flow: Create from a template (BETA) This action will start the flow of creating a design from the template > **Parameters for this action:** > > **`projectId`** - ID of the project where the design will be created > > **`folderId`** - ID of the folder where the design will be created (optional) > > **`name`** - The name I want the design to have (Optional) > > **`brandkitId`** - Only templates within that Brand Kit will be displayed. (Optional) ```json { "type": "nextgen_flow_create_from_template", "projectId": 100, "folderId": 124, // this param is optional "name": "Test design name", // this param is optional "brandkitId": 124 // this param is optional } ``` ### Flow: Create from assets (BETA) This action will start the flow of creating a design from assets (logo, images, etc.) > **Parameters for this action:** > > **`projectId`** - ID of the project where the design will be created > > **`folderId`** - ID of the folder where the design will be created (optional) > > **`name`** - The name I want the design to have (Optional) > > **`brandkitId`** - Only assets within that Brand Kit will be displayed. (Optional) ```json { "type": "nextgen_flow_create_from_assets", "projectId": 100, "folderId": 124, // this param is optional "name": "Test design name", // this param is optional "brandkitId": 124 // this param is optional } ``` ## Session Configuration The `sessionConfig` object allows users to customize their white-label session by enabling or disabling certain features like design download, share link, and comments. By providing this configuration in their JWT token, end users can control session behavior based on their specific needs. ### Object Structure ```json { "sessionConfig": { "useDownload": false, "useAdServing": false, "usePublishToMeta": false, "usePublishToGoogleAds": false, "useShareButton": true, "useShareLinkComments": true, "useAiEditText": false, "useAiEditImage": true, "useAiTranslate": false, "brandkitIds": [1, 2, 3], "hideToolbarItems": ["templates", "elements"], "hideAllToolbarItemsExcept": null } } ``` ### Properties
PropertyTypeDefaultRequiredDescription
useDownloadBooleanfalseNoEnables or disables the option to download design within the session. If true, download functionality is available; if false, it is disabled.
useShareLinkCommentsBooleanfalseNoEnables or disables the option to add comments to share links within the session. If true, comments are allowed; if false, they are not.
useShareButtonBooleantrueNoEnables or disables the option to use the share button. if true the share button appears, if false, the share button is hidden
useAiEditTextBooleantrueNoEnables or disables the usage of editing text using AI. if true this option is enabled and if false it's disabled
useAiEditImageBooleantrueNoEnables or disables the usage of editing image using AI. if true this option is enabled and if false it's disabled
useAiTranslateBooleantrueNoEnables or disables the usage of translation using AI. if true this option is enabled and if false it's disabled
useAdServingBooleanfalseNoEnables or disables the usage of Ad Serving. if true this option is enabled and if false it's disabled
usePublishToMetaBooleanfalseNoEnables or disables publishing to Meta. if true this option is enabled and if false it's disabled
brandkitIdsArray of Brandkit Ids[]NoGives you the control to limit the brandkits that are shown in AdStudio. If it's not provided, the brandkits available will depand on the brand control defined on team and project level
### Usage To configure these session options, include the `sessionConfig` object in the payload of your JWT token. This configuration will then be applied to the session. ```json { "clientId": "YOUR-CLIENT_ID", "userId": userId, "action": { "type": "edit_design", "hash": "template-hash", "editorMode": "adstudio" | "genstudio" }, "sessionConfig": { "useDownload": false, "useShareLinkComments": true, "useShareButton": true, "useAiEditText": false, "useAiEditImage": true, "useAiTranslate": false, "useAdServing": true, "usePublishToMeta": false, "brandkitIds": [123, 456] } } ``` In this example: * `useDownload: false` disables downloads for the session. * `useShareLinkComments: true` enables comments on shared links. * The share button is active (`useShareButton: true`). * AI-powered text editing is disabled (`useAiEditText: false`), while AI image editing is enabled (`useAiEditImage: true`). * AI translation is disabled (`useAiTranslate: false`). * Ad serving is active (`useAdServing: true`). * Publish to Meta is disabled (`usePublishToMeta: false` ). * Brand-specific configurations are applied based on `brandkitIds`. #### Notes * **Optional Properties**: All properties in the `sessionConfig` object are optional. If not provided, default values will apply. * You can start your session without the `sessionConfig` provided, the default values will also be applied in this case. * **Brand Kit Support**: If `brandkitIds` is not specified or is an empty array, no brand-specific configurations will be applied. ### Supported Toolbar Items (`Tools`) The following toolbar items can be specified for `hideToolbarItems` or `hideAllToolbarItemsExcept`: * `"templates"` * `"elements"` * `"brandKit"` * `"layers"` * `"slides"` * `"animator"` * `"feedTool"` * `"apps"` * `"resize"` * `"help"` ### Usage Rules for Toolbar Configuration 1. **Mutual Exclusivity**: The parameters `hideToolbarItems` and `hideAllToolbarItemsExcept` are mutually exclusive. You cannot use both at the same time. If both are provided, the session will fail to load the configuration. 2. **Functionality**: * **`hideToolbarItems`**: Specifies toolbar items to be removed from the left toolbar. * **`hideAllToolbarItemsExcept`**: Specifies toolbar items to remain visible, removing all others. ### Examples **Example 1: Hiding Specific Toolbar Items** To hide only the `"templates"` and `"elements"` toolbar items: ```json jsonCopy code{ "sessionConfig": { "hideToolbarItems": ["templates", "elements"] } } ``` **Example 2: Keeping Specific Toolbar Items Visible** To hide all toolbar items except `"templates"` and `"elements"`: ```json jsonCopy code{ "sessionConfig": { "hideAllToolbarItemsExcept": ["templates", "elements"] } } ``` #### Notes 1. **Empty Arrays**: Providing an empty array for `hideToolbarItems` or `hideAllToolbarItemsExcept` will result in no changes to the toolbar. 2. **Priority**: Ensure only one of `hideToolbarItems` or `hideAllToolbarItemsExcept` is included to avoid conflicts. 3. **User Experience**: Consider the user's workflow before hiding or limiting access to toolbar items to ensure functionality aligns with their needs. # Iframe embedding The editor is embeddable in an iframe too, using `/tokenAuth?token=`method. The only difference is that you use `app-proxy.thebrief.ai` subdomain instead `app.thebrief.ai` ```html ``` To ensure consistent integration, the iframe sends two messages to the parent window. One when the session starts and another when it ends, triggered by clicking the "End session" button. You can catch the messages using the next script: ```javascript window.addEventListener("message", (event) => { // Optionally, check the origin of the message for security purposes if (event.origin !== "https://app-proxy.thebrief.ai") return; // Handle the message console.log("Message received from iframe:", event.data); }); ``` {% code title="Session started" fullWidth="false" %} ```json { "type": "sessionStarted", "sessionId": "xxx", // id of the session that just started "initToken": "" // the JWT sent to authenticate the current session /token-auth/{token} } ``` {% endcode %} {% code title="Session ended" %} ```json { "type": "sessionEnded", "sessionId": "xxx", // id of the session that just finished } ``` {% endcode %} # Zapier integration ## Getting started with Zapier integration You’re invited to start using The Brief app on Zapier.\ \ With this integration, you can seamlessly connect The Brief to your workflows and automatically generate creatives with ease.\ \ Click [here](https://zapier.com/developer/public-invite/171524/395880/e4a19ddb7cd42ee4a1865a84fd887187) to accept the invitation and get started. ### 1. Get your The Brief designs ready The integration with Zapier allows you to automatically create design variations based on already existing designs in your account. So, to use The Brief with Zapier, you need an active subscription and a few designs or design sets under your team. Make sure the designs you'll use as templates in Zapier have their layers named, and don't use the same naming for 2 layers so they can be identified in Zapier. You'll have to indicate in Zapier which layer or element you want to change in order to generate a new design. If you have designs with multiple slides, it's best to name the layers differently, like "Heading slide1, heading slide2", etc., so they can be identified in Zapier to replace the content in each layer as you wish. Another important thing to remember when working with Zapier is to ensure that the new elements you'll use to create design variations are of similar size and format to the original elements in your template. For example, if your original heading is 4 words, try to keep the new heading to a similar size so the newly generated creative looks good. If you're new to The Brief, you can find more details in the link below. {% embed url="" %} Help Center {% endembed %} ### 2. Create an API key In your The Brief account, under your profile (upper right corner where your name is), go to **Manage account** and select **API credentials.** On this screen, you can create an API key that you'll use to connect your The Brief account to your Zapier account later on. We'll show you later how to use it.

Profile > Manage account > API credentials

Create API key to use later in Zapier

### 3. Access Zapier Use the **Access Zapier** link to start connecting The Brief and Zapier. Accept the invitation, as shown in the screenshot below, so you can locate the app in Zapier and begin building your first Zap.
{% hint style="warning" %} **Deleting an API key** will block all already configured integrations from accessing TheBrief API. That means your Zapier workflows won't work anymore, for example. Either create a new API key and replace it in the integrations you made before deleting it, or generate a new one and re-create the integrations. {% endhint %} # Setting up Zapier with The Brief Zapier is a product that allows users to integrate their web applications to automate specific tasks. It integrates with more than 5,000 apps. Zapier uses triggers and actions to automate tasks, for example: "When *this* happens, do *that."* You can use triggers, like adding a new row of data in a spreadsheet, to generate creatives automatically through The Brief API. Adding a new client in your CRM or a new product on your website or Shopify store are also possible triggers for automatically generating one or more creatives. Next, we'll see how you can access the app inside Zapier to start setting up your zaps. # Setting up the first zap Initial trigger and authentication First, you have to get your API credentials from your The Brief account. If you skipped it or haven't yet gotten your API authentication details, follow Step 2 in the document below to get them ready. {% content-ref url="/pages/Bmzw6I4XvnfRar0S9vSe" %} [Setting up Zapier with The Brief](/zapier-integration/setting-up-zapier-with-the-brief) {% endcontent-ref %} Once you have your API credentials, click the **Access Zapier** link on the same screen. You'll get to the screen below, where you have to accept the invitation to create your first zaps.
In Zapier, when setting up your first Zap, you must define a trigger that will automatically activate the app to generate creatives. A trigger can be adding a new row to a Google sheet or an Excel file where you store the details of the creatives you want to generate through Zapier, adding a product to your website or Shopify store, adding a new client to your CRM, or getting data through a form. After you set up your first trigger, you'll have to select the action that gets triggered. Search for "Creatopy" and select **Creatopy (1.0.0)**, then choose the Event **Generate creative**.
Next, you have to connect your The Brief account, so you'll get a sign-in screen like the one below. This is where you'll **use the client ID and secret key** (Client secret) you got from The Brief's **API credentials** screen. Copy and paste them into their respective fields.
From here, we'll move on to the actions you can do with the app in Zapier and finish setting up your Zap. # Setting up the action in your first zap (generate 1 creative) There are 2 types of actions you can trigger from Zapier: * Generating a variation based on a design template * Generating multiple size variations based on a template set ### Generate a variation of a design based on a template You can use this action to generate a creative variant from your team's pre-created designs or templates. That means you will automatically create a new design based on an existing template in your team by changing certain elements in the initial design. After setting an initial trigger and authenticating to use the app, you must go through each step and fill in all the required fields.
* **The template hash field** is where you'll find listed all your designs from The Brief. You have to select the design you want to use as a template to generate new creatives. {% hint style="info" %} You'll see listed in Zapier all the designs you have access to. If you want to use one of the The Brief templates, duplicate it into one of your folders. {% endhint %} * **The type of export field** refers to the kind of file you want to receive at the end once the creatives are generated. You can now select JPG, PNG, GIF, animated GIF, and MP4. We'll expand this list soon. * **The zap webhook URL field** sets a trigger for the following action. We'll explain these triggers in detail in the next steps. They allow you to automate what to do with the generated creatives: you can send them to your email inbox or cloud storage. Choose **Zap Webhook URL** if you know how to use webhooks and you want more freedom; otherwise, choose **Creative generated trigger**. After you select the template you want to use, all the elements in the template will be listed as fields you can fill in. These are the details of your new design - so fill in the fields with the details you want to include in your new creative. You can pull these details from a spreadsheet or another app, depending on where you store them. So, map the fields to the correct source of information.
Once you're done setting up the fields, you can test the action and verify if it all worked well through the message you receive. You'll receive a success message in Zapier if it works well. You can also check the details of every action and trigger on the Zap history page. Next, we'll look at how you can automatically generate multiple sizes variations of a design/template. # Setting up the action in your first zap (generate multiple creatives) How to generate multiple sizes creatives from Zapier ### **Generate multiple size variations of a design set** You can use this action to generate as many creatives of multiple sizes as you want by using a set of designs in your The Brief account as a template in Zapier. That means you can automatically generate variations of a design set. Set your initial trigger - whatever you wish to trigger the generation of the multiple-size creatives - and select **Generate creative in The Brief** as an action in your zap. Fill in all the required fields step by step.
* **The template hash field** is where you'll find listed all the design sets you have access to in The Brief. You have to select the design set you want to use as a template for your new creatives. {% hint style="info" %} You can use only the design sets you have access to. If you want to use one of the The Brief set templates, duplicate it into one of your folders. {% endhint %} * **The type of export field** refers to the kind of file you want to receive at the end once the creatives are generated. You can now select JPG, PNG, GIF, animated GIF, and MP4. We'll expand this list soon. * **The zap webhook URL field** sets a trigger for the following action. We'll explain these triggers in detail later on. They allow you to automate what to do with the generated creatives - you can send them to your email inbox or cloud storage. Choose **Zap Webhook URL** if you know how to use webhooks and want more freedom; otherwise, choose **Creative generated trigger**. After you select the template set you want to use, all the elements in the template will be listed as fields you can fill in. These are the details of your new designs - so fill in the fields with the details you want to include in your new creatives. You can pull these details from a spreadsheet or another app, depending on where you store them. So, map the fields to the correct source of information.
Once you're done setting up the fields, you can test the action and verify if it worked well through the message you receive. You'll receive a success message in Zapier if it works well. You can also check the details of every action and trigger on the Zap history page. Next, we'll look at what you can do with the generated creatives - whether it's 1 design or more. # Setting up your second zap Now, you need a trigger that will activate the next action: what to do with the newly generated creatives. There are 2 types of triggers available to use in Zapier with the app: * The trigger verifies once in a while when your creatives are ready, and once they're ready, it will push the following action to start. * The webhook trigger - which gives you more freedom if you want to use the payload returned from The Brief when your creatives are ready. # The Brief Trigger Decide what to do with your newly generated creatives ### Setting up The Brief trigger Depending on how many creatives you're generating, it can take a while for the job to be done. This trigger is fixed, and it verifies once in a while if your creatives are ready, and when they're done, it pushes the next action to start. The time it takes to push the next action depends on your Zapier subscription - for a premium subscription, the verification happens quicker and more often. Nonetheless, it works all the same. To set up this trigger, create a new zap and search for the Creatopy app. Select **Creatopy (1.0.0)** and choose the event **Creative generated trigger**.
In the previous step, when you finish setting up the action to generate creatives, when you test the action, you get a success message that also returns a code. This code needs to be used in the next step when setting up the trigger. Below is a screenshot of where to find the code. Each code will be unique to a zap, so use it only once. If you want to create multiple zaps, you must create multiple triggers. Remember that each action needs a trigger, and each trigger will activate an action.
With the code from the action in the previous zap, you paste it in the **Code** field in your Trigger zap like below.
Then, you have to test the trigger. When the creatives are successfully generated, you get a success message and the creatives' URL. If there were any problems and the job failed, you'll get an error message, which you can use to troubleshoot.
{% hint style="info" %} To get a successful message here, you must run the first zap successfully because the creatives need to be generated, so you receive a download link here. {% endhint %} All that's left to do now is to set up the following action, as in what to do with your creatives' URL - you can send them in a zip file to your inbox, send them to a cloud storage (Dropbox, Google Drive, etc.), or to another app that you use and it integrates with Zapier. # Webhook trigger Decide what to do with your newly generated creatives ### Setting up and using the webhook trigger The webhook trigger is faster than the The Brief trigger, and it will instantly push the next action in your zap to start. If you're a techie, you get more freedom to use the payload as you wish. This is the format of the incoming payload: ```json { id: "073edff5-5506-41e8-ba1b-14e5e100aa83", // Unique ID of the job status: "complete", // either complete or failed type: "jpg", // The type of the export (jpg, png, gif, mp4) creatives: [{ id: "073edff5-5506-41e8-ba1b-14e5e100aa84", // Unique ID of the generated creative status: "complete", logs: "", // Errors in case of failure url: "https://creatopy-api-0d4e56b.s3.eu-central-1.amazonaws.com/creatives/.......", creatives: [{ id: "073edff5-5506-41e8-ba1b-14e5e100aa85", // Unique ID of the generated creative size status: "complete", logs: "", // Errors in case of failure url: "https://creatopy-api-0d4e56b.s3.eu-central-1.amazonaws.com/creatives/.......", }] }] } ``` {% hint style="info" %} We support using a single design or a design set as a template to generate new creatives. * In the case of a single design, you will get only the root creatives field with one or multiple creatives according to the number of slides you have in your template. * In the case of a design set, you will get the root creatives field with one object that also contains a creatives array of generated variants from all sizes you have in your design set. {% endhint %} For your second zap, choose **Webhooks by Zapier** and select **Catch Hook,** like in the image below.
Keep the **Pick off a Child Key** field empty and click **Continue.** You'll get a webhook link like the one below.
Copy and paste the webhook link into your first zap, where you set up the action to generate creatives in the field **Zap Webhook URL**.
Verify you filled in all the required fields in the first zap (where you set up the action to generate creatives) and run the test. Then, return to your second zap (the webhook trigger) and run the zap to test the webhook. You must run your first zap successfully to get a result here, as you need the generated creatives. Use the webhook trigger that catches the generated creatives to send them to your inbox, a cloud storage, or post them live. You can further check out the Use Cases to see how to set that up. # Verify your generated creatives in app Review, edit and redownload the creatives generated through Zapier Once you set up your zaps and publish them, they'll keep running to generate new creatives according to your setup. All the creatives generated through Zapier are also automatically published in The Brief in your personal project under **Designs** in the **Generated creatives** folder.

Where to find the newly generated designs in Creatopy

The **Generated creatives** folder is automatically published when your first creative is generated from Zapier. If you delete or rename it, a new folder with an identical name will appear again when a new creative gets generated from Zapier. Inside the **Generated creatives** folder, you'll find a Zapier folder, which we recommend you don't rename or delete, as a new one with an identical name will appear in its stead, containing all the generated designs from Zapier. Each template you use in Zapier has a designated folder here, and each folder takes the template name. The entire hierarchy of folders here is generated automatically, and you shouldn't rename or delete them. You also cannot move these folders. You can, however, move, rename, and delete the creatives inside the folders. Here, you can view, edit, and redownload your creatives generated through Zapier if you want to make any changes or if there are any issues with the designs. As each generation from Zapier costs credits, in The Brief, you can make changes and redownload your creatives without further costs. If you need more people to review the generated creatives, it's best to share the folder with them - either the **Zapier** folder that contains all the designs or a particular template folder, as you need. Or use the share link for each folder or creative as you see fit. # Zapier use cases Here are a few examples of what you can do with Zapier and The Brief. These are use cases of workflows you can automate. # Generate design variations through a spreadsheet Organize your data in a spreadsheet and automate your creatives' generation when you add a new row of data. The spreadsheet should contain the details you want to include in your creative, like headline, image link, and other texts and details which will replace the layers in an existing design from your Creatopy account that you'll use as a template in Zapier. Zapier integrates with many sheet apps. You can take a look at the article below. {% embed url="" %} We'll use Google Sheets as an example, but it will work similarly with any other spreadsheet app that integrates with Zapier. You will need to set up a trigger and an action in a zap to create this workflow. ### Setting up the trigger First, set up the trigger by selecting the Google Sheets app and picking the **New Spreadsheet Row** event.
Subsequently, connect your Google account so it accesses your Google Drive. Then, pick the spreadsheet and worksheet you want to use.
Your spreadsheet has to have column headers. To test the trigger, add a new row with data to your spreadsheet and return to Zapier to test it. {% hint style="info" %} Make sure your spreadsheet has column headers for Zapier to read the data in your spreadsheet correctly. {% endhint %} ### Setting up the action In the second step of the zap, add the Creatopy Zapier app and choose the event **Generate creative**, like in the screenshot below.
If you haven't yet connected your Creatopy account to Zapier, you'll have to go to Creatopy and generate the API keys needed to authenticate in Zapier and use the Creatopy app. You can find how to do all that in the link below. {% content-ref url="/pages/qDM8wRBzCUW7ZC8v8iBo" %} [Zapier integration](/zapier-integration) {% endcontent-ref %} Continuing with the zap, you'll have to pick a design template for the generated variations, the type of export, and the webhook URL that will be called when Creatopy finishes generating the variant. You can see below how to set up a webhook trigger or leave this field empty and set a second zap using the Creatopy trigger to send the generated creatives to your inbox or cloud storage. {% content-ref url="/pages/nlE8bhjZGfLh8SCGkmIX" %} [Webhook trigger](/zapier-integration/setting-up-zapier-with-the-brief/setting-up-your-second-zap/webhook-trigger) {% endcontent-ref %} When you pick a template, Zapier will list the layers in your design template, which you need to map to your input fields (the data in your spreadsheet based on your column headers).
Finally, test the action to ensure everything is fine; you will get a message with a pending status, as shown below.
To put this workflow live, you have to publish the zap. Here are a few use cases on what to do with your newly generated creatives: {% content-ref url="/pages/6skYHVETomiTl9Cb7R03" %} [Send newly generated creatives to cloud storage](/zapier-integration/zapier-use-cases/send-newly-generated-creatives-to-cloud-storage) {% endcontent-ref %} {% content-ref url="/pages/FXindEEyDbGxlSvcnbHC" %} [Send newly generated creatives to an email inbox](/zapier-integration/zapier-use-cases/send-newly-generated-creatives-to-an-email-inbox) {% endcontent-ref %} {% content-ref url="/pages/wuqfQ5BH8QEBY2egVNVW" %} [Post newly generated creative on a social media platform](/zapier-integration/zapier-use-cases/post-newly-generated-creative-on-a-social-media-platform) {% endcontent-ref %} # Generate creatives from an e-commerce platform If you have an e-commerce or Shopify store, you can automate generating creatives when you add a new product. Zapier integrates with many e-commerce platforms; you can check the list below to see the ones they support. {% embed url="" %} We'll use a Shopify store for this example, but it will work similarly with any other store app or even your own web store if it integrates with Zapier. You will need to set up a trigger and an action in a zap to create this workflow. ### Setting up the trigger When creating a new zap, select **Shopify** as a trigger and **New Product** as the event.
Subsequently, Zapier has to connect to your Shopify account to pull in the product details from the store.
### Setting up the action In the second step of the zap, add the Creatopy Zapier app and choose the event **Generate creative**, like in the screenshot below.
If you haven't yet connected your Creatopy account to Zapier, you'll have to go to Creatopy and generate the API keys needed to authenticate in Zapier and use the Creatopy app. You can find how to do all that in the link below. {% content-ref url="/pages/qDM8wRBzCUW7ZC8v8iBo" %} [Zapier integration](/zapier-integration) {% endcontent-ref %} Continuing with the zap, you'll have to pick a design template for the generated variations, the type of export, and the webhook URL that will be called when Creatopy finishes generating the variant. You can see below how to set up a webhook trigger or leave this field empty and set a second zap using the Creatopy trigger to send the generated creatives to your inbox or cloud storage. {% content-ref url="/pages/nlE8bhjZGfLh8SCGkmIX" %} [Webhook trigger](/zapier-integration/setting-up-zapier-with-the-brief/setting-up-your-second-zap/webhook-trigger) {% endcontent-ref %} When you pick a template, Zapier will list the layers in your design template, which you need to map to your input fields (the data about the new product you just added).
Finally, test the action to ensure everything is fine; you will get a message with a pending status, as shown below.
To put this workflow live, you have to publish the zap. Here are a few use cases on what to do with your newly generated creatives: {% content-ref url="/pages/6skYHVETomiTl9Cb7R03" %} [Send newly generated creatives to cloud storage](/zapier-integration/zapier-use-cases/send-newly-generated-creatives-to-cloud-storage) {% endcontent-ref %} {% content-ref url="/pages/FXindEEyDbGxlSvcnbHC" %} [Send newly generated creatives to an email inbox](/zapier-integration/zapier-use-cases/send-newly-generated-creatives-to-an-email-inbox) {% endcontent-ref %} {% content-ref url="/pages/wuqfQ5BH8QEBY2egVNVW" %} [Post newly generated creative on a social media platform](/zapier-integration/zapier-use-cases/post-newly-generated-creative-on-a-social-media-platform) {% endcontent-ref %} # Send newly generated creatives to cloud storage We'll use Google Drive as an example for this workflow, but it should work similarly with any other cloud storage Zapier supports. You can check below all the storage apps Zapier supports. {% embed url="" %} This zap will have 2 steps: receiving the Creatopy webhook call using the Zapier built-in webhook app and uploading the generated creative variants to Google Drive. ### Setting up the trigger You have first to set up a trigger that will retrieve the creatives you generated through a different zap. You can use the Creatopy trigger or the webhook trigger. Here are the step by the step indications for each one. {% content-ref url="/pages/eThvx5DbxdbPZLkkiPed" %} [The Brief Trigger](/zapier-integration/setting-up-zapier-with-the-brief/setting-up-your-second-zap/the-brief-trigger) {% endcontent-ref %} {% content-ref url="/pages/nlE8bhjZGfLh8SCGkmIX" %} [Webhook trigger](/zapier-integration/setting-up-zapier-with-the-brief/setting-up-your-second-zap/webhook-trigger) {% endcontent-ref %} ### Setting up the action After you set up the webhook trigger correctly and ensure you get the payload from Creatopy, you need to upload the file to Google Drive. Pick the **Google drive** app in Zapier and choose the event **Upload file,** as in the screenshot below.
Once you connect your Google Drive account, you have to choose the drive and the folder and settle from where the app will get the file. We use the creative URL from the webhook call's payload for this case.
Test the action to make sure the generated file is uploaded and in the correct folder. If all works well, then the workflow is ready for publishing. {% hint style="info" %} When you use multiple creatives URLs (in case of a design set), Google Drive or other cloud storage providers will upload all sizes compressed in a zip file. {% endhint %} # Send newly generated creatives to an email inbox You can send the newly generated creatives to your email or a team's email if someone else has to verify and distribute them. Zapier integrates with many email providers and supports its own built-in actions to either send email through SMTP protocol or receive an email from a mailbox using POP or IMAP protocols. You can find more details on the following link. {% embed url="" %} This zap will have 2 steps: receiving the Creatopy webhook call using the Zapier built-in webhook app and sending the generated creatives to a Gmail inbox. ### Setting up the trigger You have first to set up a trigger that will retrieve the creatives you generated through a different zap. You can use the Creatopy trigger or the webhook trigger. Here are the step by the step indications for each one. {% content-ref url="/pages/eThvx5DbxdbPZLkkiPed" %} [The Brief Trigger](/zapier-integration/setting-up-zapier-with-the-brief/setting-up-your-second-zap/the-brief-trigger) {% endcontent-ref %} {% content-ref url="/pages/nlE8bhjZGfLh8SCGkmIX" %} [Webhook trigger](/zapier-integration/setting-up-zapier-with-the-brief/setting-up-your-second-zap/webhook-trigger) {% endcontent-ref %} ### Setting up the action After you set up the webhook trigger correctly and ensure you get the payload from Creatopy, you need to send the file to Gmail. Pick the **Gmail** app in Zapier and choose the event **Send Email**.
Connect your Gmail account to Zapier and use the creative URL from the webhook call's payload in the **Attachment** field. Then, fill in the rest of the fields as you wish.
You should receive an email with a zip file containing the creatives when you test the zap. If all works well, you can publish the zap and have this workflow live. {% hint style="info" %} When you use multiple creatives' URLs (like in the case of a design set), Gmail will attach all the sizes inside the email as separate attachments. {% endhint %} # Post newly generated creative on a social media platform Zapier integrates with many social media apps, so you could automate generating a new creative and posting it live on social media. Here's a list of the supported social media apps. {% embed url="" %} For this example, we'll get the newly generated creative from a different zap and set this zap to post it live on Instagram. {% hint style="warning" %} Because this is an automated process, you cannot preview the generated creative before it gets posted live. So, it's best to test this workflow before to ensure the quality of the generated creative is up to par. {% endhint %} ### Setting up the trigger You must first set up a trigger to retrieve the creatives you generated through a different zap. You can use the Creatopy trigger or the webhook trigger. Here are the step-by-step indications for each one. {% content-ref url="/pages/eThvx5DbxdbPZLkkiPed" %} [The Brief Trigger](/zapier-integration/setting-up-zapier-with-the-brief/setting-up-your-second-zap/the-brief-trigger) {% endcontent-ref %} {% content-ref url="/pages/nlE8bhjZGfLh8SCGkmIX" %} [Webhook trigger](/zapier-integration/setting-up-zapier-with-the-brief/setting-up-your-second-zap/webhook-trigger) {% endcontent-ref %} ### Setting up the action After you set up the webhook trigger correctly and ensure you get the payload from Creatopy, you need to post the new creative to Instagram. Pick the **Instagram for Business** app in Zapier and choose the event **Publish Photo**.
After connecting your Instagram account to allow Zapier access, you need to set up the action. For this case, we're using the creative URL from the webhook call's payload in the photo field. You can fill in the rest of the fields as you need.
Then, test the zap and verify whether the Instagram post was made correctly. You can publish the zap to put this workflow to use.