> For the complete documentation index, see [llms.txt](https://docs.thebrief.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thebrief.ai/public-api/rest-api/ad-serving.md). # 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.md#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" } ] } ```