Integration and API Spec

Integration and API Spec

Social and Digital Promotion Automation

Primary orchestration platform. All agents run inside FullSpec Automation workflows. Credentials for downstream tools are stored in its encrypted credential store and injected at runtime. Webhooks and polling nodes are configured here to trigger agents.

// Inbound trigger payload (content approved webhook)
{
  "event": "content.approved",
  "post_id": "<uuid>",
  "approved_by": "<user_email>",
  "channels": ["instagram", "linkedin", "facebook"],
  "asset_url": "https://cdn.canva.com/...",
  "caption_draft": "<string>",
  "approved_at": "<ISO8601>"
}
// Outbound: workflow execution status
{
  "execution_id": "<uuid>",
  "status": "running | success | error",
  "started_at": "<ISO8601>"
}

Handles scheduling and publishing of formatted posts to each connected social channel. The Scheduling Agent calls Buffer's API to create scheduled updates and then polls for publish confirmation.

// Input: create scheduled update
POST /1/updates/create.json
{
  "profile_ids[]": "<buffer_profile_id>",
  "text": "<formatted_caption>",
  "media[photo]": "<public_image_url>",
  "scheduled_at": <unix_timestamp_utc>,
  "shorten": true
}
// Output: scheduled update confirmation
{
  "success": true,
  "updates": [{
    "id": "<update_id>",
    "status": "buffer",
    "scheduled_at": <unix_timestamp>,
    "profile_id": "<profile_id>"
  }]
}

Supplies channel performance metrics consumed by the Reporting Agent. The integration uses the GA4 Data API (runReport endpoint) with a service account to avoid per-user OAuth token expiry issues in automated flows.

// Input: run report request
POST /v1beta/properties/XXXXXXXXX:runReport
{
  "dateRanges": [{"startDate": "7daysAgo", "endDate": "yesterday"}],
  "dimensions": [{"name": "sessionDefaultChannelGroup"}],
  "metrics": [
    {"name": "sessions"},
    {"name": "engagedSessions"},
    {"name": "screenPageViews"},
    {"name": "conversions"}
  ]
}
// Output: report rows
{
  "rows": [{
    "dimensionValues": [{"value": "Organic Social"}],
    "metricValues": [
      {"value": "1240"},
      {"value": "890"},
      {"value": "3100"},
      {"value": "42"}
    ]
  }],
  "rowCount": 1
}

Used by the Channel Formatting Agent to generate or resize creative assets to match per-channel specifications. The Canva Connect API is called to duplicate a master design, apply channel-specific dimensions, and export a publish-ready image URL.

// Input: create channel-specific design
POST /rest/v1/designs
{
  "design_type": {"type": "preset", "name": "InstagramPost"},
  "asset_id": "<master_asset_id>"
}
// Input: trigger export
POST /rest/v1/designs/{designId}/exports
{
  "format": {"type": "jpg", "quality": 90}
}
// Output: export job result
{
  "job": {
    "id": "<job_id>",
    "status": "success",
    "urls": ["https://export.canva.com/..."]
  }
}

Receives the compiled weekly performance report as a formatted message posted by the Reporting Agent to a designated channel. Optional: attaches the Google Sheets report link or a rendered summary block.

// Input: post report message
POST /api/chat.postMessage
{
  "channel": "<channel_id>",
  "text": "Weekly Social Report is ready.",
  "blocks": [
    {"type": "header", "text": {"type": "plain_text", "text": "Weekly Social Performance"}},
    {"type": "section", "fields": [
      {"type": "mrkdwn", "text": "*Sessions:* 1,240"},
      {"type": "mrkdwn", "text": "*Conversions:* 42"}
    ]}
  ]
}
// Output: message confirmation
{
  "ok": true,
  "channel": "<channel_id>",
  "ts": "<message_timestamp>"
}

// Credential 1: FullSpec Automation internal API key
Name:    FULLSPEC_INTERNAL
Type:    genericCredentialType (Header Auth)
Field:   Authorization: Bearer <FULLSPEC_API_KEY>

// Credential 2: Buffer OAuth 2.0
Name:    BUFFER_OAUTH
Type:    oAuth2Api
Fields:
  clientId:         <buffer_client_id>
  clientSecret:     <buffer_client_secret>
  accessTokenUrl:   https://api.bufferapp.com/1/oauth2/token.json
  authUrl:          https://bufferapp.com/oauth2/authorize
  scope:            profile:read updates:write updates:publish analytics:read
  grantType:        authorizationCode

// Credential 3: Google Analytics (GA4) Service Account
Name:    GA4_SERVICE_ACCOUNT
Type:    googleServiceAccount
Fields:
  serviceAccountEmail:  <sa-name>@<project>.iam.gserviceaccount.com
  privateKey:           <PEM private key from JSON key file>
  scope:                https://www.googleapis.com/auth/analytics.readonly

// Credential 4: Canva OAuth 2.0
Name:    CANVA_OAUTH
Type:    oAuth2Api
Fields:
  clientId:         <canva_client_id>
  clientSecret:     <canva_client_secret>
  accessTokenUrl:   https://api.canva.com/rest/v1/oauth/token
  authUrl:          https://www.canva.com/api/oauth/authorize
  scope:            design:content:read design:content:write design:meta:read asset:read asset:write export:read
  grantType:        authorizationCode

// Credential 5: Slack Bot Token
Name:    SLACK_BOT
Type:    slackApi
Fields:
  accessToken:  xoxb-<bot_token>

// Credential 6: Google Sheets OAuth 2.0 (or Service Account)
Name:    GSHEETS_SERVICE_ACCOUNT
Type:    googleServiceAccount
Fields:
  serviceAccountEmail:  <sa-name>@<project>.iam.gserviceaccount.com
  privateKey:           <PEM private key>
  scope:                https://www.googleapis.com/auth/spreadsheets

// Workflow constants (stored as n8n environment variables)
BUFFER_PROFILE_MAP:    {"instagram": "<id>", "linkedin": "<id>", "facebook": "<id>"}
GA4_PROPERTY_ID:       properties/XXXXXXXXX
SLACK_REPORT_CHANNEL:  <channel_id>
SLACK_OPS_CHANNEL:     <ops_channel_id>
ASSET_STORE_BASE_URL:  https://drive.google.com/... (or S3 bucket URL)
CANVA_TEMPLATE_MAP:    {"instagram": "<designId>", "linkedin": "<designId>", "facebook": "<designId>"}