Integration and API Spec

Integration and API Spec

Capacity Planning Automation

Queried by Agent 1 (Data Collection Agent) to pull all active tasks assigned to team members for the coming week. Also the destination for manual reallocation decisions made by the Ops Manager in the retained human step.

// Request: GET /tasks
GET https://app.asana.com/api/1.0/tasks
  ?workspace={ASANA_WORKSPACE_GID}
  &assignee=any
  &due_on.after={week_start_date}
  &due_on.before={week_end_date}
  &opt_fields=gid,name,assignee.name,assignee.gid,due_on,custom_fields
  &limit=100

// Response shape (per task):
{
  "gid": "1234567890",
  "name": "Deliver client proposal",
  "assignee": { "gid": "9876543210", "name": "Jordan Lee" },
  "due_on": "2025-06-09",
  "custom_fields": [
    { "name": "estimated_hours", "number_value": 4.5 }
  ]
}

Queried by Agent 1 to detect leave events, public holidays, and external blocks for each team member, reducing their available hours in the capacity dataset.

// Request: GET /calendars/{calendarId}/events
GET https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events
  ?timeMin={week_start_date}T00:00:00Z
  ?timeMax={week_end_date}T23:59:59Z
  &singleEvents=true
  &orderBy=startTime

// Response shape (per event):
{
  "summary": "LEAVE: Annual Leave",
  "start": { "date": "2025-06-09" },
  "end": { "date": "2025-06-11" },
  "status": "confirmed"
}

Queried by Agent 1 to fetch late-stage deals and their associated resource hour estimates, which are added to the incoming demand column of the capacity dataset.

// Request: POST /crm/v3/objects/deals/search (late-stage poll)
POST https://api.hubapi.com/crm/v3/objects/deals/search
Authorization: Bearer {HUBSPOT_PRIVATE_APP_TOKEN}
{
  "filterGroups": [{
    "filters": [
      { "propertyName": "dealstage", "operator": "IN",
        "values": ["{HUBSPOT_LATE_STAGE_IDS}"] },
      { "propertyName": "closedate", "operator": "LTE",
        "value": "{14_days_from_now_epoch_ms}" }
    ]
  }],
  "properties": ["dealname", "dealstage", "closedate",
                   "{HUBSPOT_RESOURCE_HOURS_PROPERTY}"],
  "limit": 100
}

// Webhook payload (Closed Won trigger):
{
  "subscriptionType": "deal.propertyChange",
  "portalId": "{HUBSPOT_PORTAL_ID}",
  "objectId": 12345,
  "propertyName": "dealstage",
  "propertyValue": "{HUBSPOT_CLOSED_WON_STAGE_ID}"
}

Written to by Agent 2 (Capacity Analysis Agent). Receives the fully calculated utilisation table, status flags, and trend row. Serves as the persistent capacity dashboard and historical log.

// Request: POST /spreadsheets/{id}/values/{range}:clear then batchUpdate
POST https://sheets.googleapis.com/v4/spreadsheets
     /{GSHEETS_SPREADSHEET_ID}/values:batchUpdate
{
  "valueInputOption": "USER_ENTERED",
  "data": [{
    "range": "{GSHEETS_DATA_RANGE}",
    "values": [
      ["Jordan Lee", 40, 38, 0, 6, "110%", "OVERLOADED", "2025-06-09"],
      ["Sam Patel",  40, 22, 8, 0, "55%",  "UNDERLOADED", "2025-06-09"]
    ]
  }]
}

Used by Agent 3 (Reporting and Notification Agent) to deliver a structured capacity alert to the operations manager's Slack channel immediately after the Google Sheets write is confirmed.

// Request: POST /chat.postMessage
POST https://slack.com/api/chat.postMessage
Authorization: Bearer {SLACK_BOT_TOKEN}
{
  "channel": "{SLACK_OPS_CHANNEL_ID}",
  "text": "Weekly Capacity Alert: 2 staff overloaded",
  "blocks": [
    { "type": "header", "text": {
        "type": "plain_text",
        "text": "Capacity Alert: Week of 9 Jun 2025" }},
    { "type": "section", "fields": [
        { "type": "mrkdwn", "text": "*Overloaded (>100%)*\nJordan Lee: 110%" },
        { "type": "mrkdwn", "text": "*Underloaded (<60%)*\nSam Patel: 55%" }
    ]},
    { "type": "actions", "elements": [
        { "type": "button", "text": { "type": "plain_text",
          "text": "Open Capacity Sheet" },
          "url": "{SLACK_CAPACITY_SHEET_URL}" }
    ]}
  ]
}

Used by Agent 3 to create or update the weekly capacity summary page visible to the leadership team. The page is either created fresh each week under a designated parent page or an existing page is updated via its page ID.

// Request: POST /pages (create weekly summary page)
POST https://api.notion.com/v1/pages
Authorization: Bearer {NOTION_INTEGRATION_TOKEN}
Notion-Version: 2022-06-28
{
  "parent": { "page_id": "{NOTION_PARENT_PAGE_ID}" },
  "properties": {
    "title": [{ "text": {
      "content": "Capacity Summary: 2025-06-09" } }]
  },
  "children": [
    { "object": "block", "type": "heading_2",
      "heading_2": { "rich_text": [{ "text": {
        "content": "Team Utilisation" } }] } },
    { "object": "block", "type": "table",
      "table": { "table_width": 3,
        "has_column_header": true, "has_row_header": false,
        "children": [ ... ] } }
  ]
}

// Credential store: variable names and descriptions
// All values injected at runtime; never logged or echoed

ASANA_ACCESS_TOKEN          // OAuth access token for Asana API
ASANA_REFRESH_TOKEN         // OAuth refresh token; used to renew ASANA_ACCESS_TOKEN
ASANA_WORKSPACE_GID         // Asana workspace GID (from URL: app.asana.com/0/{GID})
ASANA_PROJECT_GIDS          // JSON array of project GIDs to query for tasks

GCAL_SERVICE_ACCOUNT_JSON   // Full JSON key for Google service account
GCAL_TEAM_CALENDAR_IDS      // JSON array: [{staff_name, calendar_id}, ...]
GCAL_LEAVE_KEYWORDS         // JSON array of strings: ['LEAVE:', 'OOO', 'Annual Leave']
GCAL_HOURS_PER_DAY          // Integer: standard working hours per day (e.g. 8)
GCAL_PUBLIC_HOLIDAY_CALENDAR_ID  // Google Calendar ID for public holidays (may be null)

HUBSPOT_PRIVATE_APP_TOKEN   // HubSpot Private App access token
HUBSPOT_PORTAL_ID           // HubSpot portal/account ID
HUBSPOT_LATE_STAGE_IDS      // JSON array of pipeline stage IDs classed as late-stage
HUBSPOT_CLOSED_WON_STAGE_ID // Pipeline stage ID for Closed Won (webhook trigger match)
HUBSPOT_RESOURCE_HOURS_PROPERTY  // Internal name of resource hours deal property
HUBSPOT_WEBHOOK_SECRET      // Client secret for X-HubSpot-Signature-Version: v3 HMAC

GSHEETS_SERVICE_ACCOUNT_JSON  // Full JSON key (can share with GCAL if same account)
GSHEETS_SPREADSHEET_ID      // Google Sheets file ID (from URL)
GSHEETS_DATA_RANGE          // Range string, e.g. 'Capacity!A2:H'
GSHEETS_TREND_RANGE         // Range string for historical log, e.g. 'Trend!A:Z'

SLACK_BOT_TOKEN             // Slack bot OAuth token (xoxb-...)
SLACK_OPS_CHANNEL_ID        // Slack channel ID for ops manager alerts (e.g. C01ABCDEF)
SLACK_CAPACITY_SHEET_URL    // Direct URL to the Google Sheet for Slack button

NOTION_INTEGRATION_TOKEN    // Notion Internal Integration token (secret_...)
NOTION_PARENT_PAGE_ID       // Page ID of 'Capacity Reports' parent page in Notion
NOTION_DATABASE_ID          // Optional: Notion database ID if using DB over pages

SCHEDULE_TIMEZONE           // Timezone string for cron schedule, e.g. America/New_York
OVERLOAD_THRESHOLD_PCT      // Integer: utilisation % above which staff are OVERLOADED (e.g. 100)
UNDERLOAD_THRESHOLD_PCT     // Integer: utilisation % below which staff are UNDERLOADED (e.g. 60)