Skip to main content

Brand DNA from a URL

Brand DNA is the platform's model of your visual and verbal identity: palette, typography, tone, values, target audience. Generation tools use it when you pass useBrandDna: true. You can extract it from your website with a single URL. This recipe covers the full lifecycle: extract, poll, review, activate.

export NATIVEADS_API_KEY="nak_production_<keyId>.<secret>"
export BASE="https://api.nativeads.ai/v1"
export BRAND_ID="<your brand id>"   # from POST /brands

1. Start an extraction​

Provide urls, assetIds (uploaded assets), or both. At least one source is required. URLs must be public http/https; internal, loopback, and cloud-metadata addresses are rejected.

VERSION_ID=$(curl -s -X POST "$BASE/brands/$BRAND_ID/brand-dna/versions" \
  -H "Authorization: Bearer $NATIVEADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"From website v1",
    "urls":["https://www.acme-coffee.example"]
  }' | jq -r '.data.versionId')
echo "version: $VERSION_ID"

Extraction is asynchronous. The version starts in pending, moves through extracting, and lands on ready (or failed).

2. Poll until ready​

while true; do
  S=$(curl -s "$BASE/brands/$BRAND_ID/brand-dna/versions/$VERSION_ID" \
    -H "Authorization: Bearer $NATIVEADS_API_KEY" | jq -r '.data.status')
  echo "status: $S"
  case "$S" in
    ready)  break ;;
    failed) echo "extraction failed"; exit 1 ;;
    *)      sleep 5 ;;
  esac
done

3. Review the result​

The version detail carries the extracted dna payload plus a confidenceScore (1–10) and any missingFields.

curl -s "$BASE/brands/$BRAND_ID/brand-dna/versions/$VERSION_ID" \
  -H "Authorization: Bearer $NATIVEADS_API_KEY" \
  | jq '.data | {status, confidenceScore, missingFields, preview}'

To adjust a field without re-running extraction, use PUT …/versions/{versionId} (send the updatedAt concurrency token) or a partial JSON Merge Patch via the MCP patch_brand_dna_version tool.

4. Activate​

A new version is not active until you activate it. Generation with useBrandDna: true uses the active version.

curl -s -X POST "$BASE/brands/$BRAND_ID/brand-dna/versions/$VERSION_ID/activate" \
  -H "Authorization: Bearer $NATIVEADS_API_KEY" | jq '.data | {versionId, isActive}'

Confirm:

curl -s "$BASE/brands/$BRAND_ID/brand-dna/active" \
  -H "Authorization: Bearer $NATIVEADS_API_KEY" | jq '.data.versionId'

Next​