Integration and API Spec

Integration and API Spec

Brand Asset Management Automation

Google Drive serves two roles: it is the inbound staging folder that triggers Agent 1, and it is the archive destination where Agent 3 moves superseded files. Google Sheets (accessed via the same Drive API service account) is written by Agent 3 to update the asset register.

// Polling call
GET https://www.googleapis.com/drive/v3/files
  ?q='DRIVE_STAGING_FOLDER_ID' in parents and createdTime > '{{last_polled_at}}'
  &fields=files(id,name,mimeType,createdTime,owners,size)
  &orderBy=createdTime desc

// Archive move call (Agent 3)
PATCH https://www.googleapis.com/drive/v3/files/{{file_id}}
  ?addParents=DRIVE_ARCHIVE_FOLDER_ID
  &removeParents=DRIVE_STAGING_FOLDER_ID

// Sheets append call (Agent 3)
POST https://sheets.googleapis.com/v4/spreadsheets/{{SHEETS_REGISTER_ID}}/values/AssetRegister!A:G:append
  ?valueInputOption=USER_ENTERED
  body: { values: [[asset_name, asset_type, campaign, version, approved_at, brandfolder_url, drive_archive_id]] }

Brandfolder is the approved asset library. Agent 1 queries it for duplicate detection. Agent 3 uploads the approved, tagged asset, sets permissions, and marks the prior version as superseded.

// Duplicate search (Agent 1)
GET https://brandfolder.com/api/v4/collections/{{BRANDFOLDER_COLLECTION_ID}}/assets
  ?search={{asset_name_normalised}}&fields=id,name,cdn_url,status
  Authorization: Bearer {{BRANDFOLDER_API_KEY}}

// Create asset record (Agent 3)
POST https://brandfolder.com/api/v4/sections/{{section_id}}/assets
  body: { data: { attributes: { name, description, attachment_url } } }

// Mark prior version superseded (Agent 3)
PATCH https://brandfolder.com/api/v4/assets/{{prior_asset_id}}
  body: { data: { attributes: { status: 'expired' } } }

Asana hosts the brand approval workflow. Agent 2 creates a review task, assigns it to the brand lead, and polls for a completion event. Rejection routes the task back to the designer via a sub-task or a separate task in the designer's project.

// Create review task (Agent 2)
POST https://app.asana.com/api/1.0/tasks
  Authorization: Bearer {{ASANA_PAT}}
  body: {
    data: {
      name: 'Brand Approval: {{asset_name}} v{{version}}',
      projects: ['{{ASANA_APPROVAL_PROJECT_ID}}'],
      assignee: '{{ASANA_BRAND_LEAD_USER_ID}}',
      due_on: '{{now + 48h ISO date}}',
      notes: 'Asset type: {{asset_type}}\nCampaign: {{campaign}}\nDrive link: {{drive_file_url}}\nDuplicate flag: {{duplicate_flag}}'
    }
  }

// Webhook event payload (inbound, task completed)
POST {{orchestration_webhook_url}}
  X-Hook-Signature: sha256={{hmac_signature}}
  body: { events: [{ resource: { gid: '{{task_gid}}' }, action: 'changed', change: { field: 'completed', new_value: true } }] }

Slack is used by Agent 2 to send the initial approval request and the 24-hour reminder to the brand lead, and by Agent 3 to post the new-asset notification to the brand-assets channel after a successful Brandfolder upload.

// Approval request DM (Agent 2)
POST https://slack.com/api/chat.postMessage
  Authorization: Bearer {{SLACK_BOT_TOKEN}}
  body: {
    channel: '{{SLACK_BRAND_LEAD_USER_ID}}',
    text: 'Brand approval needed: {{asset_name}}',
    blocks: [
      { type: 'section', text: { type: 'mrkdwn', text: '*{{asset_name}}* ({{asset_type}}) is ready for review.\n<{{drive_file_url}}|Open file> | <{{asana_task_url}}|Asana task>' } }
    ]
  }

// New asset notification (Agent 3)
POST https://slack.com/api/chat.postMessage
  body: {
    channel: '{{SLACK_BRAND_ASSETS_CHANNEL_ID}}',
    text: 'New approved asset: {{asset_name}} v{{version}} is live in Brandfolder.',
    blocks: [
      { type: 'section', text: { type: 'mrkdwn', text: ':white_check_mark: *{{asset_name}}* v{{version}} — {{asset_type}} — <{{brandfolder_url}}|View in Brandfolder>' } }
    ]
  }

// Credential store contents
// All values are encrypted at rest. Reference by key name only in workflow steps.

// Google Drive / Sheets (service account)
GOOGLE_SERVICE_ACCOUNT_JSON       = { ... full service account JSON key ... }
DRIVE_STAGING_FOLDER_ID           = '1aBcDeFgHiJkLmNoPqRsTuVwXyZ_staging'
DRIVE_ARCHIVE_FOLDER_ID           = '2bCdEfGhIjKlMnOpQrStUvWxYz_archive'
SHEETS_REGISTER_ID                = '3cDeFgHiJkLmNoPqRsTuVwXyZa_register'

// Brandfolder
BRANDFOLDER_API_KEY               = 'bf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx'
BRANDFOLDER_ORG_KEY               = 'org_xxxxxxxxxxxxxxxx'
BRANDFOLDER_COLLECTION_ID         = 'col_xxxxxxxxxxxxxxxx'
BRANDFOLDER_SECTION_IDS           = {
  'logo':        'sec_aaaaaaaaaaaaaaaa',
  'template':    'sec_bbbbbbbbbbbbbbbb',
  'photography': 'sec_cccccccccccccccc',
  'guideline':   'sec_dddddddddddddddd',
  'other':       'sec_eeeeeeeeeeeeeeee'
}

// Asana
ASANA_PAT                         = 'ey...personal_access_token...'
ASANA_WORKSPACE_ID                = '123456789012345'
ASANA_APPROVAL_PROJECT_ID         = '987654321098765'
ASANA_BRAND_LEAD_USER_ID          = '111122223333444'   // James Okoro
ASANA_DESIGNER_USER_ID            = '555566667777888'
ASANA_WEBHOOK_SECRET              = 'wh_sec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

// Slack
SLACK_BOT_TOKEN                   = 'xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx'
SLACK_BRAND_LEAD_USER_ID          = 'U0XXXXXXXXX'   // James Okoro Slack ID
SLACK_BRAND_ASSETS_CHANNEL_ID     = 'C0XXXXXXXXX'   // #brand-assets channel