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

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}}

curl --location --request POST 'https://api.thebrief.ai/v1/adnetworks/{{design_hash}}' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--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

{
    "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}}

curl --location --request DELETE 'https://api.thebrief.ai/v1/adnetworks/{{design_hash}}' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--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

{
    "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

curl --location --request POST 'https://api.thebrief.ai/v1/adServing/{{design_hash}}/update-settings' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--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

{
    "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

{
    "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

curl --location 'https://api.thebrief.ai/v1/adServing/{{design_hash}}/generate-code' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

Response

Upon a successful execution, the response will have a status code of 200 and a JSON content type.

Response Body Example:

{
    "response": {
        "code": "<!------------------------   Untitled design-250x250   ------------------------>\n<script type=\"text/javascript\">\nvar embedConfig  = {\n    \"hash\": \"mz1q0n\",\n    \"width\": 250,\n    \"height\": 250,\n    \"t\": \"[timestamp]\",\n    \"userId\": 50,\n    \"network\": \"ADSPD\",\n    \"type\": \"html5\",\n    \"clickTag\": \"[ASClickLinkUnescaped]\",\n    \"feedRow\": \"{FEED_ROW}\",\n    \"env\": \"dev\"\n};\n</script>\n<script type=\"text/javascript\" src=\"https://live-tag.creatopy.dev/embed/embed.js\"></script>\n"
    }
}

Notes:

• You may encounter an error if you update the settings and then directly call this endpoint. The error will be like this

{
    "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):

shCopyEditcurl --location --request POST 'https://api.thebrief.ai/v1/adServing/{{design_hash}}/generate-file?format=XLSX' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json'

cURL Example (Generating CSV File):

shCopyEditcurl --location --request POST 'https://api.thebrief.ai/v1/adServing/{{design_hash}}/generate-file?format=CSV' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--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:

{
    "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.