Integration Guide

Connect Vigil to Your Agent

Vigil works as a dedicated email sub-agent for any AI system. Give your assistant, copilot, or autonomous agent full access to your email inbox through a simple REST API. It can check obligations, read thread summaries, take actions, and stay informed about everything happening in your email.

How It Works

Any system that can make HTTP calls can connect to Vigil: agent frameworks (LangChain, CrewAI, AutoGen, Semantic Kernel), personal assistants, custom bots, cron jobs, or a simple script. Authenticate with an API key and you get:

• Read the inbox — every email Vigil has processed, with AI summaries
• Check obligations — who's waiting, what deadlines are approaching
• Take actions — ignore senders, resolve threads, change alert behavior
• Access memory — facts the agent has stored across all emails
• Control behavior — add rules, modify the prompt, adjust reactivity
• Chat with the agent — natural language commands, executed autonomously

Quick Setup

1. Create an API key at Account → Developer
2. Get your watcher ID from the dashboard URL or the watchers API
3. Make API calls from your agent, script, or application

One-Line Install

curl -s https://vigil.run/vigil.sh -o vigil.sh && chmod +x vigil.sh
# Edit vigil.sh: set VK and WATCHER, then:
./vigil.sh status

Public Files

These files are available for agents, scripts, and integrations:

• vigil.run/SKILL.md — agent skill definition with API reference
• vigil.run/vigil.sh — CLI wrapper script (bash, requires curl + python3)
• vigil.run/llms.txt — machine-readable product summary for AI agents

Try It

Enter your credentials to generate ready-to-use code.

curl -s https://api.vigil.run/api/watchers/<watcher-id>/threads \
  -H "Authorization: Bearer <your-api-key>"

import requests

API_KEY = "<your-api-key>"
WATCHER = "<watcher-id>"
BASE = "https://api.vigil.run/api"

headers = {"Authorization": f"Bearer {API_KEY}"}

# Check obligations
threads = requests.get(f"{BASE}/watchers/{WATCHER}/threads", headers=headers).json()
for t in threads:
    if t.get("has_obligation"):
        print(f"Waiting: {t['subject']} from {t['from_addr']}")

# Chat with the agent
resp = requests.post(
    f"{BASE}/watchers/{WATCHER}/invoke",
    headers=headers,
    json={"message": "What needs my attention today?"}
)
print(resp.json()["response"])

const API_KEY = "<your-api-key>";
const WATCHER = "<watcher-id>";
const BASE = "https://api.vigil.run/api";

const headers = { Authorization: `Bearer ${API_KEY}` };

// Get inbox threads
const threads = await fetch(`${BASE}/watchers/${WATCHER}/threads`, { headers })
  .then(r => r.json());

// Ask the agent a question
const { response } = await fetch(`${BASE}/watchers/${WATCHER}/invoke`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ message: "Summarize today's inbox" }),
}).then(r => r.json());

API Reference

All endpoints use Authorization: Bearer vk_...

Watchers

• GET /api/watchers — list all watchers
• GET /api/watchers/:id — watcher details
• POST /api/watchers — create a watcher
• PUT /api/watchers/:id — update watcher config

Threads and Inbox

• GET /api/watchers/:id/threads — list email threads
• GET /api/watchers/:id/threads/:threadId — thread detail with emails
• POST /api/watchers/:id/threads/:threadId/close — close a thread

Agent

• POST /api/watchers/:id/invoke — chat with the watcher agent
• POST /api/watchers/:id/digest — generate an inbox digest
• GET /api/watchers/:id/memory — agent memories
• GET /api/watchers/:id/actions — action history

Account

• GET /api/usage — cost and usage breakdown
• GET /api/keys — list API keys
• POST /api/keys — create a new API key

What Your Agent Can Say to Vigil

Through the invoke endpoint, your agent gives natural language commands:

• "Ignore all emails from marketing@company.com"
• "What deadlines are coming up this week?"
• "Resolve the invoice thread, I already paid it"
• "Be more aggressive about alerting on client emails"
• "Summarize what happened in my inbox today"

Vigil executes these autonomously. Your parent agent doesn't need to understand email infrastructure. It talks to Vigil like a colleague who manages the inbox.

Agent Framework Examples

Vigil's API is framework-agnostic. Here are patterns for common setups:

• LangChain / LangGraph — wrap the invoke endpoint as a custom tool. The agent calls it when the user asks about email.
• CrewAI — assign a "mail analyst" crew member with Vigil API access. It checks obligations on a schedule and reports to the lead agent.
• AutoGen / Semantic Kernel — register Vigil endpoints as function calls. The planner invokes them when email context is needed.
• MCP (Model Context Protocol) — expose Vigil's API as MCP tools. Any MCP-compatible client can query the inbox.
• Cron / scripts — call the digest endpoint on a schedule, pipe the result to Slack, email, or a dashboard.