# 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" } ] } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.thebrief.ai/public-api/rest-api/ad-serving.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.