Integration and API Spec

Integration and API Spec

Internal Knowledge Base Management

Acts as the automation entry point. Every new form response triggers the Knowledge Triage Agent workflow. The form must be structured with fixed field names so the orchestration layer can parse responses reliably.

// Input (raw form response from polling)
response_id: string
submitted_at: ISO8601 timestamp
request_type: 'New Article' | 'Update Existing' | 'Flag as Outdated'
article_title_or_url: string
request_description: string
urgency_flag: 'Normal' | 'High'
submitter_email: string

// Output (passed to Knowledge Triage Agent)
form_response_id: string
parsed_request: { type, title_or_url, description, urgency, submitter_email }
received_at: ISO8601 timestamp

Serves as the single source of truth for all article tasks, statuses, metadata, and the published knowledge base. Both agents read from and write to Notion. The integration relies on a single Notion internal integration token with access scoped to the relevant workspace pages.

// Input (from triage agent, for task creation)
title: string
status: 'Draft'
owner_email: string
reviewer_email: string
request_type: 'New' | 'Update' | 'Flag'
priority: 'Normal' | 'High'
due_date: ISO8601 date
review_interval_days: integer
submitter_email: string
google_doc_url: string (if draft exists)

// Output (polled status change, to Review and Publish Coordinator Agent)
page_id: string
title: string
status: 'Ready for Review' | 'Approved' | 'Review Due'
owner_email: string
reviewer_email: string
next_review_date: ISO8601 date
google_doc_url: string
published_date: ISO8601 date (on publish)

Used for article drafting and inline reviewer feedback. The triage agent reads document metadata (title, last modified, sharing status) to support duplicate detection. The review coordinator retrieves the shareable link to include in Slack notifications.

// Input (from Notion task record)
google_doc_url: string
page_id: string (Notion reference)

// Output (to Slack notification payload)
doc_title: string
doc_shareable_link: string
doc_last_modified: ISO8601 timestamp

Handles all outbound notifications: direct messages to assigned owners and reviewers, team channel announcements on publication, and scheduled review reminder messages. All messages use templated Block Kit payloads with dynamic field injection.

// Input (from orchestration layer)
message_type: 'owner_assigned' | 'reviewer_notify' | 'article_published' | 'review_reminder' | 'overdue_reminder'
recipient_email: string
notion_page_id: string
article_title: string
doc_link: string
due_date: ISO8601 date (where applicable)
next_review_date: ISO8601 date (where applicable)

// Output (Slack API response)
ok: boolean
ts: string (message timestamp, stored for audit log)
channel: string

Used by subject-matter experts to embed screen recordings in how-to articles. The automation performs read-only link metadata retrieval at intake time if a Loom URL is included in the form submission, so the triage agent can confirm the link is accessible before writing it to the Notion task record.

// Input (conditional, from form response parse)
loom_url: string (optional, present only if submitter included one)
extracted_video_id: string

// Output (to Notion task record, if successful)
loom_title: string
loom_share_status: 'public' | 'workspace' | 'private'
loom_embed_url: string

// Credential store entries (all required before build proceeds)

// Google Workspace
GOOGLE_OAUTH_CLIENT_ID          = '<from Google Cloud Console>'
GOOGLE_OAUTH_CLIENT_SECRET      = '<from Google Cloud Console>'
GOOGLE_OAUTH_REFRESH_TOKEN      = '<generated via OAuth consent flow>'
GOOGLE_SERVICE_ACCOUNT_EMAIL    = '<service account email>'
GOOGLE_FORMS_FORM_ID            = '<target form ID from Forms URL>'
GOOGLE_FORMS_SHEET_ID           = '<linked response Sheet ID from Drive URL>'
GOOGLE_DRIVE_ROOT_FOLDER_ID     = '<shared drafts folder ID>'

// Notion
NOTION_INTEGRATION_TOKEN        = '<Internal Integration Token from notion.so/my-integrations>'
NOTION_ARTICLES_DB_ID           = '<Articles database ID from Notion URL>'
NOTION_KB_PARENT_PAGE_ID        = '<Knowledge Base parent page ID>'

// Slack
SLACK_BOT_TOKEN                 = '<xoxb- bot token from Slack app settings>'
SLACK_ANNOUNCEMENT_CHANNEL_ID   = '<#kb-updates channel ID>'
SLACK_FALLBACK_CHANNEL_ID       = '<#ops-alerts channel ID>'

// Loom
LOOM_API_KEY                    = '<API key from Loom Developer settings>'

// Workflow state variables (managed by orchestration layer, not secrets)
WORKFLOW_1_LAST_PROCESSED_TS    = '<ISO8601, updated each poll cycle>'
WORKFLOW_2_LAST_POLL_TS         = '<ISO8601, updated each poll cycle>'
WORKFLOW_2_PROCESSED_PAGE_IDS   = '<comma-separated list, cleared on each 24h cycle>'

// Template references (stored as workflow config, not credential store)
TEMPLATE_OWNER_ASSIGNED         = 'slack_block_owner_assigned_v1'
TEMPLATE_REVIEWER_NOTIFY        = 'slack_block_reviewer_notify_v1'
TEMPLATE_ARTICLE_PUBLISHED      = 'slack_block_article_published_v1'
TEMPLATE_REVIEW_REMINDER        = 'slack_block_review_reminder_v1'
TEMPLATE_OVERDUE_REMINDER       = 'slack_block_overdue_reminder_v1'
LOOM_URL_REGEX                  = '(?:loom\.com/share/)([a-zA-Z0-9]+)'