Integration and API Spec

Integration and API Spec

Regulatory Change Monitoring

Feedly is the feed aggregation layer for the Source Monitor Agent. It holds all configured regulatory RSS feeds and monitored web sources. The automation polls the Feedly Streams API to retrieve new articles since the last fetch timestamp. Custom web watchers (for sources without RSS) are configured as Feedly Board integrations where supported, or handled via scraper fallback documented separately.

// Input
GET /v3/streams/contents
  streamId: {FEEDLY_STREAM_ID}
  count: 50
  unreadOnly: true
  newerThan: {LAST_RUN_TIMESTAMP}
// Output
items[]: { id, title, originId, origin.title, published, summary.content, alternate[0].href, author }

Airtable serves as the compliance change register, the deduplication store, and the topic-to-owner routing table. Three tables are required within one base: tbl_register (primary log), tbl_routing (owner routing rules), and tbl_dedup (processed item ID store). All three must be created with the schema defined in the Developer Handover Pack before build begins.

// Input (record creation, Agent 1 and 2)
POST /v0/{AIRTABLE_BASE_ID}/{AIRTABLE_REGISTER_TABLE_ID}
  fields: { item_id, source_name, source_url, published_date,
            effective_date, topic_category, relevance_score,
            plain_summary, suggested_owner, status }
// Input (dedup check, Agent 1)
GET /v0/{AIRTABLE_BASE_ID}/{AIRTABLE_DEDUP_TABLE_ID}
  filterByFormula: {item_id}='{feedly_item_id}'
// Output (routing lookup, Agent 3)
GET /v0/{AIRTABLE_BASE_ID}/{AIRTABLE_ROUTING_TABLE_ID}
  filterByFormula: {topic_category}='{classified_topic}'
  -> fields: { slack_channel, slack_user_id, owner_email }

Notion is used by the Relevance and Summary Agent to store plain-language summary documents and to provide topic classification context (keyword lists, jurisdiction definitions, and scoring rules stored as a Notion database). The automation reads the classification ruleset from a designated Notion database and writes summary documents as child pages under a configured parent page.

// Input (classification ruleset read, Agent 2)
GET /v1/databases/{NOTION_CLASSIFICATION_DB_ID}/query
  -> rows[]: { topic_keyword, jurisdiction, relevance_weight, owner_tag }
// Input (summary page creation, Agent 2)
POST /v1/pages
  parent: { page_id: {NOTION_SUMMARY_PARENT_PAGE_ID} }
  properties: { title: { title: [{ text: { content: item_title } }] } }
  children: [ paragraph block with plain_summary text ]
// Output
  -> created page: { id, url, created_time }

Slack is used by the Alert and Digest Agent to post real-time structured alerts to topic-specific channels and to tag the responsible owner directly. Overdue follow-up reminders are also sent via Slack if an action item has not been acknowledged within the configured number of days. A dedicated Slack App must be created in the workspace before build.

// Input (alert post, Agent 3)
POST /api/chat.postMessage
  channel: {slack_channel_id}  // from tbl_routing
  blocks: [
    { type: header, text: item_title }
    { type: section, text: plain_summary }
    { type: context, elements: [ source_name, effective_date, relevance_score ] }
    { type: actions, elements: [ Acknowledge button -> airtable record URL ] }
  ]
  text: fallback plain text for notification previews
// Output
  -> { ok: true, ts: message_timestamp, channel: channel_id }

Gmail is used by the Alert and Digest Agent to send the weekly compliance digest email to the compliance lead and any configured management recipients. The email is assembled from all Airtable records created in the previous seven days and formatted using a stored HTML template. Overdue action reminders may also be sent by email as a secondary channel alongside Slack.

// Input (digest send, Agent 3)
POST /gmail/v1/users/{GMAIL_SENDER_ADDRESS}/messages/send
  raw: base64url_encoded_RFC2822_message
    To: {GMAIL_DIGEST_RECIPIENTS}
    From: {GMAIL_SENDER_ADDRESS}
    Subject: Weekly Compliance Digest: {week_start_date} to {week_end_date}
    Content-Type: multipart/alternative
      text/plain: plain digest body
      text/html: rendered HTML from GMAIL_DIGEST_TEMPLATE_ID
// Output
  -> { id: message_id, threadId, labelIds: ['SENT'] }

// Credential store contents
// Format: VARIABLE_NAME : type : description

// Feedly
FEEDLY_CLIENT_ID          : secret  : OAuth 2.0 client ID from Feedly developer portal
FEEDLY_CLIENT_SECRET      : secret  : OAuth 2.0 client secret
FEEDLY_ACCESS_TOKEN       : secret  : Short-lived access token (auto-refreshed on 401)
FEEDLY_REFRESH_TOKEN      : secret  : Long-lived refresh token
FEEDLY_STREAM_ID          : config  : Target collection stream ID (e.g. enterprise/...) 
FEEDLY_BOARD_IDS          : config  : Comma-separated board IDs for secondary streams
LAST_RUN_TIMESTAMP        : state   : Unix ms timestamp of last successful Feedly poll

// Airtable
AIRTABLE_PAT              : secret  : Personal Access Token (service account)
AIRTABLE_BASE_ID          : config  : Base ID (appXXXXXXXXXXXXXX format)
AIRTABLE_REGISTER_TABLE_ID: config  : tbl_register table ID
AIRTABLE_ROUTING_TABLE_ID : config  : tbl_routing table ID
AIRTABLE_DEDUP_TABLE_ID   : config  : tbl_dedup table ID
AIRTABLE_WEBHOOK_SECRET   : secret  : Shared secret for inbound webhook validation

// Notion
NOTION_TOKEN              : secret  : Internal Integration Token (secret_...)
NOTION_CLASSIFICATION_DB_ID: config : Database ID for topic/jurisdiction ruleset
NOTION_SUMMARY_PARENT_PAGE_ID: config: Parent page ID for new summary child pages
NOTION_API_VERSION        : config  : 2022-06-28

// Slack
SLACK_BOT_TOKEN           : secret  : Bot OAuth token (xoxb-...)
SLACK_SIGNING_SECRET      : secret  : Used for future event API signature validation
SLACK_DEFAULT_CHANNEL     : config  : Fallback channel ID (C012AB3CD format)
SLACK_OVERDUE_REMINDER_DAYS: config : Days before overdue reminder fires (default: 5)

// Gmail
GMAIL_CLIENT_ID           : secret  : Google OAuth 2.0 client ID
GMAIL_CLIENT_SECRET       : secret  : Google OAuth 2.0 client secret
GMAIL_REFRESH_TOKEN       : secret  : Offline refresh token
GMAIL_SENDER_ADDRESS      : config  : Sending email address
GMAIL_DIGEST_RECIPIENTS   : config  : Comma-separated To addresses for weekly digest
GMAIL_DIGEST_TEMPLATE_ID  : config  : Key for HTML template in orchestration template store

// Classification and routing
RELEVANCE_THRESHOLD       : config  : Minimum relevance score to pass classification (0-100)
SCAN_SCHEDULE_CRON        : config  : Cron expression for Agent 1 daily poll
DIGEST_SCHEDULE_CRON      : config  : Cron expression for Monday digest send
OVERDUE_CHECK_CRON        : config  : Cron expression for daily overdue check