Integration and API Spec

Integration and API Spec

SEO Content Production Workflow

Notion is the central status trigger and write-back destination for all three agents. The automation platform polls the target database for status-field changes or receives webhook events via the Notion API. All Notion database property names must match the agreed schema exactly; any rename at the Notion level will break trigger conditions.

// Trigger poll — POST /v1/databases/{NOTION_DATABASE_ID}/query
Filter: { property: 'Status', select: { equals: 'Approved' } }
// Write-back — PATCH /v1/pages/{page_id}
Body: { properties: { 'Brief Link': { url: '<google_docs_url>' }, 'Status': { select: { name: 'Brief Ready' } } } }

Ahrefs provides keyword volume, keyword difficulty, SERP competitor URLs, and related keyword suggestions for the Brief Generation Agent. All API calls use the v3 REST API. The integration is read-only; no data is written back to Ahrefs.

// GET https://apiv3.ahrefs.com/v3/keywords-explorer/overview
Headers: { Authorization: 'Bearer {AHREFS_API_KEY}' }
Params: { keyword: '<target_keyword>', country: '{AHREFS_DEFAULT_COUNTRY}', select: 'volume,difficulty,cpc,keyword_difficulty' }
// Response extract
{ volume: 2400, difficulty: 34, cpc: 1.20, keyword_difficulty: 34 }
// GET https://apiv3.ahrefs.com/v3/serp-overview
Params: { keyword: '<target_keyword>', country: '{AHREFS_DEFAULT_COUNTRY}', select: 'url,title,traffic' }
// Response extract — top 5 competitor URLs passed to brief template

Google Docs serves three functions: Agent 1 creates a new brief document from a master template; Agent 2 reads the draft document content to send to Surfer SEO; Agent 3 reads the approved draft content to construct the WordPress post body. A service account with domain-wide delegation is the recommended auth approach to avoid per-user OAuth token management.

// Step 1: Copy template to Briefs folder
POST https://www.googleapis.com/drive/v3/files/{GOOGLE_BRIEF_TEMPLATE_ID}/copy
Body: { name: '<Article Title> — Brief', parents: ['{GOOGLE_BRIEFS_FOLDER_ID}'] }
// Step 2: Replace placeholders
POST https://docs.googleapis.com/v1/documents/{new_doc_id}:batchUpdate
Body: { requests: [ { replaceAllText: { containsText: { text: '{{target_keyword}}' }, replaceText: '<keyword>' } }, ... ] }
// Step 3 (Agent 2 / Agent 3): Read document body
GET https://docs.googleapis.com/v1/documents/{doc_id}
Extract: body.content[].paragraph.elements[].textRun.content — concatenate all runs

The SEO Audit Agent submits the article draft text to the Surfer SEO Content Editor API, retrieves the overall content score and section-level recommendations, and packages these into a scorecard delivered via Slack. This is a synchronous request-response integration; the agent waits for the score before proceeding.

// POST https://api.surferseo.com/api/v1/audits
Headers: { Authorization: 'Bearer {SURFER_API_KEY}', Content-Type: 'application/json' }
Body: { keyword: '<target_keyword>', content: '<article_plain_text>', language: 'en' }
// Response
{ score: 74, sections: [ { heading: 'Introduction', score: 68, recommendation: 'Add 2 uses of secondary keyword' }, ... ] }
// Sections where score < SURFER_SCORE_THRESHOLD are extracted and included in the Slack scorecard

Slack delivers two distinct notifications: a brief-ready DM to the assigned writer after Agent 1 completes, and a SEO scorecard alert to the content manager after Agent 2 completes. Both messages are sent by a dedicated Slack bot. Incoming webhooks are used for channel messages; the chat.postMessage API method is used for direct messages.

// Brief-ready DM — POST https://slack.com/api/chat.postMessage
Headers: { Authorization: 'Bearer {SLACK_BOT_TOKEN}' }
Body: { channel: '<writer_slack_user_id>', text: 'Your brief for "<Article Title>" is ready.', blocks: [ { type: 'section', text: { type: 'mrkdwn', text: '*Brief:* <{brief_url}|View in Google Docs>\n*Keyword:* <target_keyword>\n*Due:* <publish_date>' } } ] }
// SEO scorecard alert — POST https://slack.com/api/chat.postMessage
Body: { channel: '{SLACK_EDITOR_CHANNEL_ID}', text: 'SEO Audit complete for "<Article Title>". Score: <score>/100.', blocks: [ { type: 'section', text: { type: 'mrkdwn', text: '*Flagged sections:*\n<formatted_flag_list>' } } ] }

The CMS Publishing Agent creates a new WordPress post via the WordPress REST API, populating all metadata fields from the Notion article record, and retrieves the canonical URL of the scheduled or published post to write back to Notion. The REST API must be enabled on the WordPress installation (it is enabled by default on self-hosted WordPress.org installs).

// Step 1: Upload featured image
POST {WP_SITE_URL}/wp-json/wp/v2/media
Headers: { Authorization: 'Basic {base64(WP_APP_USERNAME:WP_APP_PASSWORD)}', Content-Disposition: 'attachment; filename="<image_filename>"', Content-Type: 'image/jpeg' }
Body: <binary image data fetched from Notion 'Featured Image URL' field>
Response: { id: 4821 } — store as featured_media_id
// Step 2: Create post
POST {WP_SITE_URL}/wp-json/wp/v2/posts
Body: { title: '<meta_title>', content: '<html_body>', excerpt: '<meta_description>', slug: '<slug>', status: 'future', date: '<iso8601_publish_date>', categories: [<category_id>], tags: [<tag_ids>], featured_media: <featured_media_id>, meta: { _yoast_wpseo_title: '<meta_title>', _yoast_wpseo_metadesc: '<meta_description>' } }
Response: { id: 9103, link: 'https://example.com/<slug>/' } — write link back to Notion

// CREDENTIAL STORE — all entries required before any workflow runs
// Notion
NOTION_API_TOKEN          = 'secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
NOTION_DATABASE_ID        = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

// Google (service account JSON stored as a single escaped string)
GOOGLE_SERVICE_ACCOUNT_JSON   = '{"type":"service_account","project_id":"...", ...}'
GOOGLE_BRIEF_TEMPLATE_ID      = '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms'
GOOGLE_BRIEFS_FOLDER_ID       = '1a2b3c4d5e6f7g8h9i0jKLMNOPQRSTUVWX'
GOOGLE_DRAFTS_FOLDER_ID       = '9z8y7x6w5v4u3t2s1r0qPONMLKJIHGFEDC'

// Ahrefs
AHREFS_API_KEY            = 'ahrefs_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxx'
AHREFS_DEFAULT_COUNTRY    = 'us'
AHREFS_MONTHLY_ROW_CAP    = 500

// Surfer SEO
SURFER_API_KEY            = 'surfer_xxxxxxxxxxxxxxxxxxxxxxxxxxxx'
SURFER_SCORE_THRESHOLD    = 70

// Slack
SLACK_BOT_TOKEN               = 'xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx'
SLACK_CONTENT_MANAGER_USER_ID = 'U01ABCDEFGH'
SLACK_WRITER_CHANNEL_ID       = 'C02ABCDEFGH'
SLACK_EDITOR_CHANNEL_ID       = 'C03ABCDEFGH'

// WordPress
WP_SITE_URL               = 'https://yourcompany.com'
WP_APP_USERNAME           = 'wp-automation-user'
WP_APP_PASSWORD           = 'xxxx xxxx xxxx xxxx xxxx xxxx'
WP_DEFAULT_CATEGORY_ID    = 5
WP_TAG_MAP                = '{"seo":12,"content-marketing":18,"blogging":24}'

// Platform config (non-secret, stored as config variables)
POLL_INTERVAL_SECONDS     = 60
MAX_ARTICLE_CHARS_SURFER  = 50000
RETRY_MAX_ATTEMPTS        = 3
RETRY_BACKOFF_SECONDS     = [30, 120, 300]