> ## Documentation Index > Fetch the complete documentation index at: https://developer.box.com/llms.txt > Use this file to discover all available pages before exploring further. # Build an AI-powered DAM system with Box > Extract brand metadata with Box AI, move files through a review lifecycle, invite vendors to a Draft folder, and add approved files to a Box Hub. export const AgentPromptBuilder = ({stacks = [], rootId = "agent-prompt-root"}) => { const languages = Array.isArray(stacks) ? stacks : []; const [language, setLanguage] = useState(languages[0]?.language || ""); const [framework, setFramework] = useState(languages[0]?.frameworks?.[0]?.name || ""); const activeLanguage = languages.find(entry => entry.language === language) || languages[0]; const frameworks = activeLanguage?.frameworks || []; const activeFramework = frameworks.find(entry => entry.name === framework)?.name || frameworks[0]?.name || ""; useEffect(() => { if (!activeLanguage?.language || !activeFramework) return; const root = document.getElementById(rootId); if (!root) return; const key = `${activeLanguage.language}||${activeFramework}`; const panels = root.querySelectorAll("[data-agent-stack]"); panels.forEach(panel => { const match = panel.getAttribute("data-agent-stack") === key; panel.hidden = !match; panel.style.display = match ? "" : "none"; }); }, [activeLanguage?.language, activeFramework, rootId]); if (languages.length === 0) { return
AgentPromptBuilder needs a non-empty stacks prop.
; } const selectClassName = "w-full min-w-[10rem] appearance-none rounded-lg border border-gray-200 bg-white px-3 py-2 pr-9 text-sm font-medium text-gray-900 transition-colors focus:outline-none focus:ring-2 focus:ring-gray-400/30 dark:border-gray-700 dark:bg-gray-900 dark:text-gray-100 dark:focus:ring-gray-500/30"; const handleLanguageChange = event => { const next = languages.find(entry => entry.language === event.target.value) || languages[0]; setLanguage(next.language); setFramework(next.frameworks?.[0]?.name || ""); }; return <>

Build this tutorial with your coding agent

Choose your stack, then copy this ready-to-use prompt into Codex, Claude Code, Cursor, or another coding agent.

; }; export const RelatedLinks = ({title, items = []}) => { const getBadgeClass = badge => { if (!badge) return "badge-default"; const badgeType = badge.toLowerCase().replace(/\s+/g, "-"); return `badge-${badge === "ガイド" ? "guide" : badgeType}`; }; if (!items || items.length === 0) { return null; } return
{}

{title}

{}
{items.map((item, index) => {} {item.badge} {} {item.label} )}
; }; export const Link = ({href, children, className, ...props}) => { const localizedHref = localizeLink(href); return {children} ; }; When someone uploads a product image, logo, or campaign file to a Box intake folder, this service extracts brand metadata and writes those values onto the file. You can advance the file through the entire lifecycle, from Draft to Retired. External agencies upload into Draft only, while regional teams find approved files in a Box Hub. Digital asset management helps you store, find, share, and retrieve files in one library with access controls. Most of those files are unstructured, so models cannot use them until you attach metadata. See AI-powered digital asset management. ## Before you start Complete these Box setup steps before you build. You need: * A free Box developer account, or a Box Enterprise account with Box AI enabled. Box Hubs is required only for the publish step. Box Archive is optional and requires Enterprise Advanced. * A Box application configured with **Client Credentials Grant** authentication, authorized in the Admin Console, with these scopes: * Read and write all files and folders stored in Box * Manage AI * Manage webhooks * Python 3.11+ for the Build by hand path. For the agent path, a coding agent such as Codex, Claude Code, or Cursor, and a runtime for the stack you choose. Installing Box Agent Skills helps the agent use current Box APIs. Copy the metadata template key, the six lifecycle folder IDs, and the enterprise ID. The agent prompt and your `.env` file use them. The metadata template lists the fields Box AI extracts and the lifecycle status your service writes. Create it once. Every processed file then returns values in this shape. This step requires Admin access. If you do not have access, contact your Box administrator. 1. Open the [Box Admin Console](https://app.box.com/master) and select **Metadata**. 2. Select **New** and name it `Brand Asset`. 3. Add the following fields: | Field name | Type | Description | | - | - | - | | Asset Type | Dropdown | Add options, for example `Product imagery`, `Logo`, `Marketing material` | | Campaign | Text | Campaign or collection name visible on or associated with the asset | | Product Name | Text | Product, SKU, or offering the asset represents | | Brand | Text | Brand or sub-brand | | Lifecycle Status | Dropdown | Add options, for example `Draft`, `Creative review`, `Legal review`, `Approved`, `Published`, `Retired` | | Usage Rights | Dropdown | Add options, for example `Internal only`, `External`, `Restricted` | | Description | Text | Short visual summary of the asset | | Capture Date | Date | Camera capture date from EXIF, if present | | Camera Make | Text | Camera manufacturer from EXIF, if present | | Camera Model | Text | Camera model from EXIF, if present | 4. Select **Save**, then reopen the template and copy the template key from under the **Template Name**. You need it for the prompt and for `.env`. Box derives each field's key from its display name in camel case. `Asset Type` becomes `assetType`. If you rename a field, confirm its key in the Admin Console. For a detailed walkthrough, see Customizing Metadata Templates. Box AI Extract reads what is visible in the file: layout, on-image text, and OCR on JPEG, PNG, TIFF, and WEBP. It does not read camera EXIF. Box AI can still fill `captureDate` from visible content, so that value is not necessarily the camera capture date. The optional local EXIF step replaces it when the file has EXIF data. Create this folder tree in Box. Each lifecycle stage is its own folder so you can grant access per stage. Vendors see Draft. Reviewers see their stage. The Hub indexes Published only. 1. In Box, create a folder called `Brand DAM` with this structure: ```text theme={null} Brand DAM/ ├── Draft/ # vendor drop zone and intake ├── Creative Review/ ├── Legal Review/ ├── Approved/ ├── Published/ # Hub indexes this folder └── Retired/ # superseded or expired masters ``` 2. Note each **folder ID** from the URL. For example, if the URL is `https://app.box.com/folder/123456789`, the folder ID is `123456789`. 3. **Share every folder in this tree with your application's service account** as **Editor**. A CCG app runs as a service account. That account has no access to your content until you invite it. Without this share, API calls return 404 Not found. Find the service account email in the [Developer Console](https://app.box.com/developers/console). Open your app, select the **Configuration** tab, and copy the **Service Account ID** from the **App Details** sidebar. It looks like `AutomationUser_xxxxx_xxxxxx@boxdevedition.com`. Invite that email as a collaborator on `Brand DAM` with the **Editor** role so child folders inherit access. The same template and folder pattern can hold owner's manuals, warranty PDFs, or maintenance docs. Add a dropdown value such as `Support document` if you extend the template. This tutorial covers brand assets only. ## Build with an agent Gather these values from [Before you start](#before-you-start): * Metadata template key. Copy it from the template you created. * Six lifecycle folder IDs. Copy them from the folder URLs. * Enterprise ID. Copy it from the [Developer Console](https://app.box.com/developers/console) using the icon in the top-right. Choose your stack and copy the prompt. The prompt lists these as already created. The agent reads them from environment variables and does not try to create them. Replace the `` and `` placeholders if you want the agent to pre-fill `.env`. Otherwise leave them and fill `.env` yourself after scaffolding.
```md Python + Flask theme={null} Build a production-minded AI-powered digital asset management (DAM) service by following this Box tutorial: https://developer.box.com/tutorials/ai-powered-dam Use Python with Flask. Target Python 3.11+, use pip and a virtual environment. Install exactly one Box package: "boxsdk~=10.0" (do NOT also install box-sdk-gen — both ship the box_sdk_gen module and conflict). Import Box APIs with `from box_sdk_gen import ...`. Also install flask, python-dotenv, and pytest for tests. Optional EXIF: pillow. Prerequisites already done in Box (see 'Before you start' in the tutorial). Do NOT try to create these; read their values from environment variables: - Enterprise metadata template key: (fields assetType, campaign, productName, brand, lifecycleStatus, usageRights, description; optional captureDate, cameraMake, cameraModel) - Lifecycle folder IDs, each shared with the app service account as Editor: DRAFT_FOLDER_ID, CREATIVE_REVIEW_FOLDER_ID, LEGAL_REVIEW_FOLDER_ID, APPROVED_FOLDER_ID, PUBLISHED_FOLDER_ID, RETIRED_FOLDER_ID - Enterprise ID: - CCG app scopes enabled: Read and write all files and folders stored in Box, Manage AI, and Manage webhooks Mirror the Python samples in the tutorial for Box client, extract, metadata, lifecycle, and vendor invite. Use Flask for the HTTP server as in the Build by hand path, except that POST /webhook responds before processing (see step 2 below). The app must: 1. Authenticate to Box with Client Credentials Grant (enterprise / service account). Use BOX_ENTERPRISE_ID — do NOT authenticate as a managed user. 2. Receive Box FILE.UPLOADED webhook events at POST /webhook. Box expects a 2xx response within 30 seconds and retries otherwise, and AI extract can take longer. Return 200 right away and run extract and the metadata write in the background (an in-process background task is fine here; note in the README that production should use a durable queue). Log the extracted fields so the local curl test shows them in the server output. 3. Ignore events for files that are not images Box AI Extract supports (JPEG, JPG, PNG, TIFF, TIF, WEBP). Return 200 with a skipped/ignored status. 4. Call POST /2.0/ai/extract_structured using the brand-asset metadata template (template_key + scope enterprise), not inline fields. 5. Extract assetType, campaign, productName, brand, usageRights, and description. Set lifecycleStatus to Draft on intake. Missing fields are OK. 6. Write the extracted values back to the file as Box enterprise metadata: - Try create first. - On 409 Conflict (instance already exists), JSON-Patch update with op 'add' for each returned field (not 'replace'). Do not fail retests of the same file. 7. Expose POST /lifecycle that accepts {"file_id", "lifecycle_status"} and: - Updates lifecycleStatus on the metadata instance (409-safe upsert). - Moves the file into the folder that matches that status. Allowed statuses: Draft, Creative review, Legal review, Approved, Published, Retired. 8. Include invite_vendor.py (runnable as a CLI script) that collaborates an external email onto DRAFT_FOLDER_ID as Viewer Uploader (role "viewer uploader"), with notify=true and an expires_at date. Treat a 409 with error code user_already_collaborator as already invited; do not match on the error message text. In the README, note that expires_at requires the enterprise setting 'Automatically remove invited collaborators: Allow folder owners to extend the expiry date', that the enterprise setting can override the date sent, and to omit expires_at if the setting is off. 9. Return clear JSON responses and handle Box API errors safely. 10. Include a local test path that does not require a public webhook URL (curl POST to localhost:5000/webhook with a simulated FILE.UPLOADED payload). Read configuration from environment variables: BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID, BOX_METADATA_TEMPLATE_KEY, DRAFT_FOLDER_ID, CREATIVE_REVIEW_FOLDER_ID, LEGAL_REVIEW_FOLDER_ID, APPROVED_FOLDER_ID, PUBLISHED_FOLDER_ID, RETIRED_FOLDER_ID. DRAFT_FOLDER_ID is the intake folder for the production webhook. Do not require folder IDs inside POST /webhook except as documented. Create a complete runnable project with: - box_client.py, extract.py, metadata.py, lifecycle.py, invite_vendor.py, and app.py (POST /webhook and POST /lifecycle) matching the tutorial modules - a flat Flask layout matching the tutorial (no unnecessary packages) - dependency and run commands - .env.example and .gitignore files - brief webhook signature verification guidance (link or comment is enough; do not block the local curl test on signature checks) - idempotency: the 409 metadata upsert above is required - focused unit tests and a README with setup and test steps Do not invent a Box EXIF API. Camera EXIF (captureDate, cameraMake, cameraModel) is optional: download the file and parse it locally (for example Pillow). Read captureDate from DateTimeOriginal in the Exif sub-IFD (0x8769) in preference to DateTime in the main block, which is the last-modified time. Skip EXIF when the file has none. Box AI Extract reads visual/OCR content only, but it can still fill captureDate from visible content; EXIF values overwrite it when present. Never hard-code credentials. Add concise comments only where the Box-specific behavior is not obvious. Before writing code, summarize the architecture and list the files you will create. ```

Review generated code before using it in production. Never paste Box credentials into your coding agent.

When the agent finishes, copy `.env.example` to `.env` and fill in your client ID, client secret, enterprise ID, metadata template key, and folder IDs. Then skip ahead to [Run and verify](#run-and-verify). Prefer to write the code yourself? See [Build by hand](#build-by-hand) below. ## Build by hand Use this path to write the code yourself, or as a reference if the agent drifts. Complete [Before you start](#before-you-start) first, then follow the steps in order. Samples are Python. You can also clone a working sample if you prefer to start from running code: Clone the Flask app, add your Box credentials, and run. 1. Open your terminal and create a new project directory: ```bash theme={null} mkdir brand-dam && cd brand-dam ``` 2. Install dependencies: ```bash theme={null} python3 -m venv .venv source .venv/bin/activate pip install "boxsdk~=10.0" flask python-dotenv ``` After activation, your terminal prompt shows `(.venv)` at the beginning. Every time you open a new terminal window or tab, re-activate the virtual environment with `source .venv/bin/activate` from the project directory. If you see `ModuleNotFoundError`, the venv is usually not activated. 3. Create a `.env` file and add the following content. Replace the placeholder values with credentials from the Box Developer Console and the folder IDs from [Before you start](#before-you-start): ```bash theme={null} BOX_CLIENT_ID=your_client_id BOX_CLIENT_SECRET=your_client_secret BOX_ENTERPRISE_ID=your_enterprise_id BOX_METADATA_TEMPLATE_KEY=your_metadata_template_key DRAFT_FOLDER_ID=your_draft_folder_id CREATIVE_REVIEW_FOLDER_ID=your_creative_review_folder_id LEGAL_REVIEW_FOLDER_ID=your_legal_review_folder_id APPROVED_FOLDER_ID=your_approved_folder_id PUBLISHED_FOLDER_ID=your_published_folder_id RETIRED_FOLDER_ID=your_retired_folder_id ``` Never commit `.env` files to version control. Add `.env` to your `.gitignore`. The `.env` file stores sensitive values. Your code reads them by **name**. When you copy the code in the following steps, keep the quoted variable names exactly as shown. Do not replace them with your actual credentials. Create the Box client module in your project directory: ```python theme={null} # box_client.py import os from dotenv import load_dotenv from box_sdk_gen import ( BoxClient, BoxCCGAuth, CCGConfig, ) load_dotenv() def get_box_client() -> BoxClient: config = CCGConfig( client_id=os.getenv("BOX_CLIENT_ID"), client_secret=os.getenv("BOX_CLIENT_SECRET"), enterprise_id=os.getenv("BOX_ENTERPRISE_ID"), ) auth = BoxCCGAuth(config=config) return BoxClient(auth=auth) ``` Client Credentials Grant is recommended for server-to-server automations where no end user is present. For other authentication options, see Select an authentication method. Create the extraction module. It takes a file ID, calls Box AI with your metadata template, and returns structured brand fields. Structured extract runs OCR on JPEG, PNG, TIFF, and WEBP, so you do not convert product shots or logos to PDF first. See Extract metadata from file (structured). ```python theme={null} # extract.py import os from dotenv import load_dotenv from box_sdk_gen import ( AiItemBase, BoxClient, CreateAiExtractStructuredMetadataTemplate, CreateAiExtractStructuredMetadataTemplateTypeField, ) load_dotenv() def extract_brand_fields(client: BoxClient, file_id: str) -> dict: template_key = os.getenv("BOX_METADATA_TEMPLATE_KEY") result = client.ai.create_ai_extract_structured( items=[AiItemBase(id=file_id)], metadata_template=CreateAiExtractStructuredMetadataTemplate( template_key=template_key, type=CreateAiExtractStructuredMetadataTemplateTypeField.METADATA_TEMPLATE, scope="enterprise", ), ) return result.to_dict()["answer"] ``` The template tells Box AI which fields to look for. Product name, campaign lettering, and brand marks come back as keys, not a free-text caption. Create the metadata module. After extraction, this function attaches the values to the file as a metadata instance. ```python theme={null} # metadata.py import os from dotenv import load_dotenv from box_sdk_gen import ( BoxAPIError, BoxClient, CreateFileMetadataByIdScope, UpdateFileMetadataByIdRequestBody, UpdateFileMetadataByIdRequestBodyOpField, UpdateFileMetadataByIdScope, ) load_dotenv() def apply_metadata(client: BoxClient, file_id: str, metadata: dict) -> dict: template_key = os.getenv("BOX_METADATA_TEMPLATE_KEY") try: attached = client.file_metadata.create_file_metadata_by_id( file_id=file_id, scope=CreateFileMetadataByIdScope.ENTERPRISE, template_key=template_key, request_body=metadata, ) except BoxAPIError as error: if error.response_info.status_code != 409: raise attached = client.file_metadata.update_file_metadata_by_id( file_id=file_id, scope=UpdateFileMetadataByIdScope.ENTERPRISE, template_key=template_key, request_body=[ UpdateFileMetadataByIdRequestBody( op=UpdateFileMetadataByIdRequestBodyOpField.ADD, path=f"/{key}", value=value, ) for key, value in metadata.items() ], ) return attached.to_dict() ``` Creating metadata succeeds only the first time. If the file already has an instance of the template, Box returns `409 Conflict on Metadata Instance`. This function then sends a JSON-Patch update. You can re-run the service on a file you already processed, including duplicate webhook deliveries. Use the `add` operation, not `replace`. `add` sets a value whether or not the field is already present. The update still succeeds when Box AI returns fewer fields than the previous run. After metadata is attached, the fields are searchable and visible in the Box web app. Use metadata queries to find External-rights logos for a campaign, or to list files still in Legal review. Create the lifecycle module. Each allowed status maps to a folder. The function updates status and moves the file in one step so current files do not sit in the wrong folder. ```python theme={null} # lifecycle.py import os from box_sdk_gen import BoxClient, UpdateFileByIdParent from metadata import apply_metadata STATUS_FOLDER_ENV = { "Draft": "DRAFT_FOLDER_ID", "Creative review": "CREATIVE_REVIEW_FOLDER_ID", "Legal review": "LEGAL_REVIEW_FOLDER_ID", "Approved": "APPROVED_FOLDER_ID", "Published": "PUBLISHED_FOLDER_ID", "Retired": "RETIRED_FOLDER_ID", } def advance_lifecycle( client: BoxClient, file_id: str, lifecycle_status: str ) -> dict: env_name = STATUS_FOLDER_ENV.get(lifecycle_status) if not env_name: raise ValueError( f"Unknown lifecycle status: {lifecycle_status}. " f"Allowed: {', '.join(STATUS_FOLDER_ENV)}" ) folder_id = os.getenv(env_name) apply_metadata(client, file_id, {"lifecycleStatus": lifecycle_status}) client.files.update_file_by_id( file_id, parent=UpdateFileByIdParent(id=folder_id) ) return {"file_id": file_id, "lifecycle_status": lifecycle_status, "folder_id": folder_id} ``` Creative and legal teams can still review in Box with comments, versions, tasks, or a Box Automate approval workflow. This function records which folder holds the current file after that decision. Agencies and freelancers must not see Legal review or Published masters. Invite them to Draft only, as Viewer Uploader, with an expiration date. ```python theme={null} # invite_vendor.py import os from datetime import datetime, timedelta, timezone from dotenv import load_dotenv from box_sdk_gen import ( BoxAPIError, CreateCollaborationAccessibleBy, CreateCollaborationAccessibleByTypeField, CreateCollaborationItem, CreateCollaborationItemTypeField, CreateCollaborationRole, ) from box_client import get_box_client load_dotenv() def invite_vendor(login: str, days: int = 30) -> dict: client = get_box_client() folder_id = os.getenv("DRAFT_FOLDER_ID") expires_at = datetime.now(timezone.utc) + timedelta(days=days) try: collaboration = client.user_collaborations.create_collaboration( item=CreateCollaborationItem( type=CreateCollaborationItemTypeField.FOLDER, id=folder_id, ), accessible_by=CreateCollaborationAccessibleBy( type=CreateCollaborationAccessibleByTypeField.USER, login=login, ), role=CreateCollaborationRole.VIEWER_UPLOADER, expires_at=expires_at, notify=True, ) except BoxAPIError as error: if error.response_info.code != "user_already_collaborator": raise return {"status": "already_collaborator", "login": login} return collaboration.to_dict() if __name__ == "__main__": import sys email = sys.argv[1] if len(sys.argv) > 1 else os.getenv("VENDOR_EMAIL") if not email: raise SystemExit("Pass a vendor email or set VENDOR_EMAIL") print(invite_vendor(email)) ``` Do not put unpublished brand files in a folder that already has an open shared link, or that already has external collaborators outside Draft. Invite named users. Set an expiration on the collaboration. Add only the Published folder to a Hub. `expires_at` depends on the **Automatically remove invited collaborators: Allow folder owners to extend the expiry date** setting in the Admin Console **Enterprise Settings**. If that setting is off, omit `expires_at`. The enterprise setting can also override the date you send, so check the expiration on the new collaboration in Box. External email invites can also require the vendor domain on the collaboration allowlist. For role definitions, see Share content with a user. Create the HTTP application. It receives webhook notifications when new files arrive in Draft. It also exposes a lifecycle endpoint your review app can call. ```python theme={null} # app.py import json from dotenv import load_dotenv from flask import Flask, jsonify, request from box_client import get_box_client from extract import extract_brand_fields from lifecycle import advance_lifecycle from metadata import apply_metadata load_dotenv() app = Flask(__name__) IMAGE_EXTENSIONS = (".jpg", ".jpeg", ".png", ".tif", ".tiff", ".webp") @app.route("/webhook", methods=["POST"]) def handle_webhook(): payload = request.get_json() if payload.get("trigger") != "FILE.UPLOADED": return jsonify({"status": "ignored"}), 200 file_id = payload["source"]["id"] file_name = payload["source"]["name"] if not file_name.lower().endswith(IMAGE_EXTENSIONS): return jsonify({"status": "skipped, not a supported image"}), 200 client = get_box_client() extracted = extract_brand_fields(client, file_id) extracted["lifecycleStatus"] = "Draft" print(f"Extracted from {file_name}: {json.dumps(extracted, indent=2)}") apply_metadata(client, file_id, extracted) print(f"Metadata applied to file {file_id}") return jsonify({"status": "processed", "file_id": file_id}), 200 @app.route("/lifecycle", methods=["POST"]) def handle_lifecycle(): body = request.get_json() file_id = body["file_id"] lifecycle_status = body["lifecycle_status"] client = get_box_client() result = advance_lifecycle(client, file_id, lifecycle_status) return jsonify(result), 200 if __name__ == "__main__": app.run(port=5000) ``` In production, verify webhook signatures to confirm that requests originate from Box. See Verify webhook signatures. This handler runs Box AI extraction before it responds, which keeps the local test simple. Box expects a `2xx` response within 30 seconds and retries the delivery if it does not get one. Extraction can take long enough to miss that window. In production, return `200` right away and process the file from a queue. See **Respond before processing** in [Scaling to production](#scaling-to-production). After scaffolding, your project directory contains these files: ```text theme={null} brand-dam/ ├── .env ├── .venv/ ├── app.py ├── box_client.py ├── extract.py ├── invite_vendor.py ├── lifecycle.py └── metadata.py ``` When you finish scaffolding, continue to [Run and verify](#run-and-verify). ## Run and verify Test extraction locally without a public URL or webhook. The request body matches what Box sends when a new file arrives. Open two terminal windows at the same time. Terminal 1 runs the server and must stay running. Terminal 2 sends a test request. 1. **Terminal 1.** Start the server. Make sure you are in the `brand-dam` directory: ```bash Python theme={null} # Flask cd ~/brand-dam source .venv/bin/activate python3 app.py # FastAPI (idiomatic package layout) cd ~/brand-dam source .venv/bin/activate uvicorn app.main:app --host 127.0.0.1 --port 5000 ``` ```bash TypeScript theme={null} # Express (flat tutorial layout) cd ~/brand-dam npx tsx app.ts # Fastify (idiomatic src/ layout) cd ~/brand-dam npm start ``` ```bash Node theme={null} # Express cd ~/brand-dam node app.js # NestJS cd ~/brand-dam npm start ``` ```bash Java theme={null} # Spring Boot cd ~/brand-dam export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH" # if needed mvn spring-boot:run # Quarkus cd ~/brand-dam export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH" # if needed mvn quarkus:dev ``` ```bash .NET theme={null} # ASP.NET Core or Minimal APIs cd ~/brand-dam dotnet run ``` The server listens on port 5000. Leave this terminal running. 2. **Terminal 2.** Send a test request. Upload a JPEG or PNG product image to the Draft folder in Box. Copy the file ID from the file URL. For `https://app.box.com/file/123456789`, the file ID is `123456789`. Use the file ID, not the folder ID. ```bash theme={null} curl -X POST http://127.0.0.1:5000/webhook \ -H "Content-Type: application/json" \ -d '{ "trigger": "FILE.UPLOADED", "source": { "id": "", "name": "autumn-campaign-hero.jpg" } }' ``` 3. **Check the result.** Switch back to Terminal 1. The extracted fields print, then a confirmation that metadata was applied: ```text theme={null} Extracted from autumn-campaign-hero.jpg: { "assetType": "Product imagery", "campaign": "Autumn 2026", "productName": "Trail Runner", "brand": "Northwind", "usageRights": "External", "description": "Hero pack shot of Trail Runner sneakers on a trail", "lifecycleStatus": "Draft" } Metadata applied to file 123456789 ``` Open the file in Box and select the **Metadata** tab to verify the values. 4. **Advance the file.** After creative and legal sign-off, move it to Published. ```bash theme={null} curl -X POST http://127.0.0.1:5000/lifecycle \ -H "Content-Type: application/json" \ -d '{ "file_id": "", "lifecycle_status": "Published" }' ``` Confirm the file is in the **Published** folder and `lifecycleStatus` is `Published`. ## Register a webhook for production The local curl test matches what Box sends. For production, Box needs a public HTTPS endpoint. ```bash theme={null} curl -X POST https://api.box.com/2.0/webhooks \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "target": { "id": "", "type": "folder" }, "address": "", "triggers": ["FILE.UPLOADED"] }' ``` Replace `` with your Draft folder ID and set `address` to your HTTPS URL with `/webhook` appended. Once registered, a supported image uploaded to Draft triggers extraction and metadata writes. ## Publish approved assets to a Box Hub After files reach Published, add that folder to a Hub. Regional teams and agency partners then search and ask questions against files approved for external use, not drafts. Box Hubs inherit permissions from the source files. Create a file called `publish_hub.py`: ```python theme={null} import os from dotenv import load_dotenv from box_sdk_gen import ( FolderReferenceV2025R0, HubItemOperationV2025R0, HubItemOperationV2025R0ActionField, ) from box_client import get_box_client load_dotenv() def main(): client = get_box_client() hub = client.hubs.create_hub_v2025_r0( "Brand asset library", description=( "Approved product imagery, logos, and marketing materials. " "Use only files in this hub for external distribution." ), ) client.hub_items.manage_hub_items_v2025_r0( hub.id, operations=[ HubItemOperationV2025R0( action=HubItemOperationV2025R0ActionField.ADD, item=FolderReferenceV2025R0(id=os.getenv("PUBLISHED_FOLDER_ID")), ) ], ) print(f"Hub ready: {hub.title} (ID: {hub.id})") if __name__ == "__main__": main() ``` Run the script once from the project directory, with your virtual environment active and `.env` loaded: ```bash theme={null} python3 publish_hub.py ``` A successful run prints `Hub ready: Brand asset library (ID: …)`. Open `https://app.box.com/hubs/`. Files you later move to Published with `POST /lifecycle` show up in this hub. Do not run the script again for each file; that creates another hub. The CCG service account owns the hub. **Hubs** in the Box web app lists hubs for the signed-in user, so this hub does not appear there until you collaborate your managed user onto it (for example as co-owner). Hub endpoints require the `box-version: 2025.0` header. The v10 SDK methods above send it. See Box Hubs overview and the RFP answer bank tutorial to ask questions against hub content. Creating a hub as the CCG service account requires Box Hubs to be enabled for that account. If create fails, enable **Generate user access tokens** and authenticate as a managed user who can create hubs. The answer bank tutorial shows that auth path. ## Optional: parse camera EXIF locally Box does not expose camera EXIF through the metadata or AI APIs. Box AI Extract covers visual and OCR fields. If you need capture date or camera model, download the file, parse EXIF locally, and merge those values into the same metadata instance. 1. From your project directory, activate the virtual environment and install Pillow: ```bash theme={null} source .venv/bin/activate pip install pillow ``` Install into this venv, not the system Python on your machine. 2. Create `exif.py`: ```python theme={null} import io from datetime import datetime from box_sdk_gen import BoxClient from PIL import Image from PIL.ExifTags import TAGS def enrich_exif(client: BoxClient, file_id: str) -> dict: content = client.downloads.download_file(file_id) data = content.read() if hasattr(content, "read") else content image = Image.open(io.BytesIO(data)) raw = image.getexif() if not raw: return {} tagged = {TAGS.get(key, key): value for key, value in raw.items()} # DateTimeOriginal is in the Exif sub-IFD (0x8769), not the main block tagged.update({TAGS.get(key, key): value for key, value in raw.get_ifd(0x8769).items()}) enrichment = {} make = tagged.get("Make") model = tagged.get("Model") captured = tagged.get("DateTimeOriginal") or tagged.get("DateTime") if make: enrichment["cameraMake"] = str(make).strip() if model: enrichment["cameraModel"] = str(model).strip() if captured: try: parsed = datetime.strptime(str(captured), "%Y:%m:%d %H:%M:%S") enrichment["captureDate"] = parsed.strftime("%Y-%m-%dT00:00:00Z") except ValueError: pass return enrichment ``` 3. If you built by hand: in `app.py`, import `enrich_exif` and merge its return value into `extracted` after Box AI extract and before `apply_metadata`: ```python theme={null} from exif import enrich_exif ``` Inside `handle_webhook`, after you set `lifecycleStatus` to `Draft`: ```python theme={null} try: extracted.update(enrich_exif(client, file_id) or {}) except Exception: pass ``` If you used the agent path, your project may already include these lines. Search `app.py` for `enrich_exif`. You still need Pillow in the venv. 4. Test with the same local `POST /webhook` request from [Run and verify](#run-and-verify). Use a camera or phone JPEG that contains EXIF, not a logo PNG with no camera data. In the server log, look for `cameraMake`, `cameraModel`, and `captureDate` alongside the Box AI fields. Confirm the same values on the file **Metadata** tab in Box. Logos and exports without EXIF leave those three fields empty. That is expected. ## Optional: retire large-format media to Box Archive The Retired folder keeps superseded campaigns out of the Hub. Use Box Archive when large video or print masters should be owned by the enterprise, not the previous user. Archive APIs require Enterprise Advanced. They also require the Global Content Manager (GCM) scope, which Box Support enables. They are not available on the Free Developer Plan. To archive a retired file, create an archive with `POST /archives`, then move the file by setting `parent.id` to the archive ID. Availability, scopes, and which endpoints your app can call depend on your Box plan and enterprise configuration. Confirm those in the guides below before you extend this service: ## Scaling to production Box waits 30 seconds for a `2xx` response to each webhook delivery. If it does not get one, it retries the delivery. Box AI extraction can take several seconds per image, and longer on large files, so the inline handler in `app.py` can time out and trigger retries that call Box AI again. In production, validate the payload, add the file ID to a job queue, and return `200` immediately. A separate worker runs extraction and writes metadata. See Webhooks (v2) for delivery and retry behavior. Box webhook delivery can produce duplicates. The 409 fallback in `apply_metadata` keeps the write safe, but a duplicate still calls Box AI a second time. To skip that work, check for an existing instance with `GET /2.0/files/:id/metadata/enterprise/:template` at the top of the handler. Return early if `lifecycleStatus` is already set. If a vendor replaces a draft in place, let extraction run so metadata matches the latest version. Collaborate external users on Draft only. Do not cascade Editor access from `Brand DAM` to vendors. If an agency needs a specific published file, collaborate on that file or on a Hub, not the whole tree. For high-volume drop folders, use enterprise events rather than webhooks. Enterprise events are a polling stream that holds events until you consume them. That works for batch processing thousands of files. ## Troubleshooting Your Python virtual environment is not activated. Run `source .venv/bin/activate` from the project directory before running any `python3` commands. Each new terminal tab needs its own activation. Check your `.env` file: * Verify `BOX_CLIENT_ID` and `BOX_CLIENT_SECRET` match Developer Console > Configuration. * Confirm `BOX_ENTERPRISE_ID` is your enterprise ID (Admin Console > Account & Billing, or Developer Console > icon in the top-right > Copy Enterprise ID). * Ensure your app is authorized and the app type is Client Credentials Grant. The service account does not have access to the file or folder. Invite the service account email (Developer Console > your app > **Configuration** > **App Details** sidebar) as a collaborator with **Editor** on `Brand DAM`. The `BOX_METADATA_TEMPLATE_KEY` value in your `.env` file is missing or empty. Add the template key you noted in [Before you start](#before-you-start). The file already has an instance of the template. Add the 409 fallback shown in **4. Write metadata back to the file**. To retest with a clean file, remove the instance from the file's **Metadata** tab, or delete it through the API: ```bash theme={null} curl -X DELETE "https://api.box.com/2.0/files//metadata/enterprise/" \ -H "Authorization: Bearer " ``` `POST /lifecycle` only accepts the six dropdown values from the template, including the space in `Creative review` and `Legal review`. Check the JSON body against those strings exactly. The template, folders, and enterprise ID come from [Before you start](#before-you-start). An agent cannot create the Admin Console template. Re-paste the prompt with the prerequisites block intact, or follow [Build by hand](#build-by-hand). ## Next steps Query a curated Hub with Box AI after you publish approved assets. See the full API specification for structured extraction, including image formats.