Integration and API Spec

Integration and API Spec

Content Calendar Management

Primary data store and trigger source for all three agents. The Notion integration token must be issued as an internal integration from the workspace settings and shared with the specific database pages used in this automation.

// Notion poll response (simplified)
GET /v1/databases/{NOTION_DATABASE_ID}/query
Authorization: Bearer {NOTION_API_TOKEN}
Content-Type: application/json

// Filter: new rows or rows where Deadline = today
{
  "filter": {
    "or": [
      { "property": "Status", "select": { "equals": "Brief Sent" } },
      { "property": "Deadline", "date": { "equals": "today" } }
  ]}
}

// Page update (status write-back)
PATCH /v1/pages/{page_id}
{ "properties": { "Status": { "select": { "name": "Scheduled" } } } }

Outbound messaging tool used by the Calendar Orchestrator Agent (brief dispatch, overdue reminders) and the Review and Publish Agent (reviewer notification, revision routing). A dedicated Slack App must be created in the target workspace.

// Send brief to writer (direct message)
POST https://slack.com/api/chat.postMessage
Authorization: Bearer {SLACK_BOT_TOKEN}
{
  "channel": "{writer_dm_channel_id}",
  "blocks": [
    { "type": "header", "text": { "type": "plain_text", "text": "New Content Brief" } },
    { "type": "section", "text": { "type": "mrkdwn",
      "text": "*Topic:* {notion.Topic}\n*Format:* {notion.Format}\n*Deadline:* {notion.Deadline}\n*Channel:* {notion.Channel}\n*Audience:* {notion.Target Audience}" } },
    { "type": "actions", "elements": [
      { "type": "button", "text": { "type": "plain_text", "text": "Open in Notion" },
        "url": "https://notion.so/{page_id}" }
    ]}
  ]
}

Used by the Review and Publish Agent to create scheduled posts on approval, and by the Performance Sync Agent to retrieve weekly engagement metrics for all published pieces.

// Create scheduled post
POST https://api.bufferapp.com/1/updates/create.json
Authorization: Bearer {BUFFER_ACCESS_TOKEN}
{
  "profile_ids": ["{BUFFER_PROFILE_IDS[notion.Channel]}"],
  "text": "{notion.approved_copy}",
  "media": { "link": "{notion.Media URL}" },
  "scheduled_at": "{notion.Deadline | toISO8601UTC}"
}

// Fetch post metrics (Performance Sync)
GET https://api.bufferapp.com/1/updates/{update_id}/interactions.json
  ?event=likes&access_token={BUFFER_ACCESS_TOKEN}

// Response fields used:
// interactions.likes, interactions.comments, interactions.shares, statistics.reach

Receives campaign record creation and update calls from the Review and Publish Agent when a piece is scheduled or published. Uses the Private App authentication model rather than OAuth to avoid user-linked token expiry.

// Create or update campaign record
POST https://api.hubapi.com/crm/v3/objects/marketing_events
Authorization: Bearer {HUBSPOT_PRIVATE_APP_TOKEN}
{
  "properties": {
    "hs_event_name": "{notion.Topic}",
    "hs_event_type": "CONTENT_PUBLISH",
    "hs_start_date": "{notion.Deadline | toISO8601UTC}",
    "hs_external_account_id": "{HUBSPOT_CAMPAIGN_OWNER_ID}",
    "hs_external_event_id": "{notion.page_id}"
  }
}

// Fallback: log note on contact
POST https://api.hubapi.com/crm/v3/objects/notes
{
  "properties": {
    "hs_note_body": "Content published: {notion.Topic} on {notion.Channel} at {notion.Deadline}",
    "hs_timestamp": "{now | toISO8601UTC}"
  }
}

// Credential store contents (key names only — no values stored here)

NOTION_API_TOKEN              // Notion internal integration token
NOTION_DATABASE_ID            // Content calendar database ID (e.g. 'a1b2c3d4e5f6...')

SLACK_BOT_TOKEN               // Bot User OAuth Token (xoxb-...)
SLACK_MARKETING_MANAGER_USER_ID  // HubSpot user ID for routing fallback
SLACK_DEFAULT_REVIEW_CHANNEL  // Channel ID for reviewer notifications (e.g. 'C0123ABCDE')

BUFFER_ACCESS_TOKEN           // OAuth 2.0 access token
BUFFER_REFRESH_TOKEN          // OAuth 2.0 refresh token
BUFFER_CLIENT_ID              // App client ID
BUFFER_CLIENT_SECRET          // App client secret
BUFFER_PROFILE_IDS            // JSON map: { "LinkedIn": "abc", "Twitter": "def", "Instagram": "ghi" }

HUBSPOT_PRIVATE_APP_TOKEN     // Private App Bearer token
HUBSPOT_CAMPAIGN_OWNER_ID     // HubSpot user ID of the marketing manager

WORKSPACE_TIMEZONE            // e.g. 'America/New_York' — used by Agent 3 schedule trigger