Update to Ultralayer

{
  "description": "Turn any alertable Ultralayer endpoint into a realtime monitor that emails, telegrams, or webhooks new results. Operations are create_alert, get_alerts, execute_alert, activate_alert, deactivate_alert, and delete_alert.",
  "included_files": [],
  "name": "alerts",
  "skill_md_contents": "---\nname: alerts\ndescription: Turn any alertable Ultralayer endpoint into a realtime monitor that emails, telegrams, or webhooks new results. Operations are create_alert, get_alerts, execute_alert, activate_alert, deactivate_alert, and delete_alert.\n---\n\n# Alerts\n\nAlerts wrap an existing Ultralayer endpoint, poll it on a schedule, skip what was already delivered, and push new matches to email, Telegram, and/or a webhook. Same filters and queries as the underlying endpoint — plus schedule and delivery. Alerts are billed as the underlying endpoint calls — there is no alert surcharge.\n\n| Operation | Role |\n|-----------|------|\n| `create_alert` | Validate + persist, return the created alert |\n| `get_alerts` | List alerts with recent attempts and deliveries |\n| `activate_alert` / `deactivate_alert` | `active` ↔ `paused` |\n| `execute_alert` | Run now (same path as scheduled execution) |\n| `delete_alert` | Permanent delete |\n\n---\n\n## When to use\n\n**Use alerts when you need:**\n- Continuous monitoring of Wire, developments, filings, events, or any other alertable path\n- Delivery to inbox, Telegram, or a webhook without running your own cron\n- The same conditions you already validated interactively, left running\n\n**Do not use alerts when you need:**\n- A one-shot answer → call the underlying endpoint directly\n- To alert on endpoints that are not in the alertable set below\n\n---\n\n## Use cases\n\n**Company wire monitor** — Get emailed when a company prints material news with strong positive or negative tone, skipping copycat syndication.\n```json\n{\n  \"name\": \"Apple important news\",\n  \"path\": \"/v0/search/list_wire\",\n  \"arguments\": {\n    \"entities\": [\"Apple Inc.\"],\n    \"novelty\": [\"new\", \"update\", \"correction\"],\n    \"entity_relevance\": [\"primary\", \"significant\"],\n    \"min_entity_sentiment\": 0.3,\n    \"max_entity_sentiment\": -0.3,\n    \"detail\": \"full\"\n  },\n  \"interval_minutes\": 15,\n  \"threshold\": 1,\n  \"receivers\": [{ \"type\": \"email\" }]\n}\n```\nSentiment min/max together = strong positive **or** strong negative. Novelty drops syndication duplicates.\n\n**Semantic Monitoring** — Watch a theme by meaning (not just a ticker) and push new matching passages to email and a webhook.\n```json\n{\n  \"name\": \"Hormuz Oil Passages\",\n  \"path\": \"/v0/search/semantic_search\",\n  \"arguments\": {\n    \"queries\": [\"Strait of Hormuz tanker disruption Brent crude\"],\n    \"max_tokens\": 1000,\n    \"min_utility_score\": 0.5,\n    \"min_cosine_similarity\": 0.75,\n    \"detail\": \"standard\"\n  },\n  \"interval_minutes\": 30,\n  \"receivers\": [\n    { \"type\": \"email\" },\n    { \"type\": \"webhook\", \"url\": \"https://hooks.example.com/ultralayer\" }\n  ]\n}\n```\n\n**Ticker development feed** — Get pinged when important new developments land for a ticker, with who is affected already scored.\n```json\n{\n  \"name\": \"Tesla Developments\",\n  \"path\": \"/v0/search/search_developments\",\n  \"arguments\": {\n    \"symbols\": [\"TSLA\"],\n    \"min_importance_score\": 0.7,\n    \"limit\": 20,\n    \"detail\": \"full\"\n  },\n  \"interval_minutes\": 30,\n  \"receivers\": [{ \"type\": \"telegram\", \"chat_id\": \"123456789\" }]\n}\n```\n\n**Tracked event lifecycle** — Follow one known story (earnings cycle, M&A, etc.) and get notified as new developments attach to it.\n```json\n{\n  \"name\": \"Tesla 2026 Financial Event\",\n  \"path\": \"/v0/search/retrieve_event_developments\",\n  \"arguments\": {\n    \"event_id\": 125,\n    \"limit\": 20,\n    \"include_future_developments\": true,\n    \"detail\": \"standard\"\n  },\n  \"interval_minutes\": 60,\n  \"lookback_minutes\": 180,\n  \"receivers\": [{ \"type\": \"email\" }]\n}\n```\nDiscover `event_id` via `search_events` or a development hit first.\n\n**Events scan (M&A)** — Stay on top of new deal activity without polling for mergers yourself.\n```json\n{\n  \"name\": \"M&A Events\",\n  \"path\": \"/v0/search/search_events\",\n  \"arguments\": {\n    \"event_type\": \"merger_acquisition\",\n    \"developments_per_event\": 1,\n    \"limit\": 10,\n    \"detail\": \"essential\"\n  },\n  \"interval_minutes\": 60,\n  \"receivers\": [{ \"type\": \"email\" }]\n}\n```\n\n**Guidance raised or cut** — Across the market, get emailed when a company revises an official outlook up or down.\n```json\n{\n  \"name\": \"Guidance raised or cut\",\n  \"path\": \"/v0/filings/list_guidance\",\n  \"arguments\": {\n    \"revision_direction\": [\"raised\", \"lowered\"],\n    \"detail\": \"standard\",\n    \"limit\": 10\n  },\n  \"interval_minutes\": 60,\n  \"receivers\": [{ \"type\": \"email\" }]\n}\n```\n\n**KPI definition and disclosure** — Across the market, get pinged when a release changes how a metric is calculated, or starts or stops highlighting a named KPI.\n```json\n{\n  \"name\": \"KPI definition and disclosure\",\n  \"path\": \"/v0/filings/list_changes\",\n  \"arguments\": {\n    \"change_categories\": [\"metric_definition\", \"disclosed_metric\"],\n    \"detail\": \"standard\",\n    \"limit\": 10\n  },\n  \"interval_minutes\": 60,\n  \"receivers\": [{ \"type\": \"email\" }]\n}\n```\n\n**Guide versus actual** — Get emailed when a prior guide significantly exceeds or significantly misses the reported result.\n```json\n{\n  \"name\": \"Guidance versus actual\",\n  \"path\": \"/v0/filings/list_guidance_outcomes\",\n  \"arguments\": {\n    \"outcomes\": [\"significantly_exceeded\", \"significantly_missed\"],\n    \"detail\": \"standard\",\n    \"limit\": 10\n  },\n  \"interval_minutes\": 60,\n  \"receivers\": [{ \"type\": \"email\" }]\n}\n```\n\n---\n\n## Alertable endpoints\n\n| `path` | What you’re monitoring |\n|--------|------------------------|\n| `/v0/search/list_wire` | Filtered headlines |\n| `/v0/search/semantic_search` | PIT / utility-filtered corpus passages |\n| `/v0/search/search_developments` | Structured developments |\n| `/v0/search/search_events` | Events with recent activity |\n| `/v0/search/retrieve_event_developments` | Developments on a known `event_id` |\n| `/v0/filings/list_guidance` | Official outlook series that moved in the window |\n| `/v0/filings/list_changes` | Wording changes in the window |\n| `/v0/filings/list_guidance_outcomes` | Company guidance versus the reported actual |\n\nWire for headlines. Developments/events for structured lifecycle. Thematic / corpus passage monitors use path `/v0/search/semantic_search`. `list_guidance` for the official outlook and revision. `list_changes` for wording changes between releases. `list_guidance_outcomes` for guide versus actual.\n\n---\n\n## Create params\n\n| Field | Notes |\n|-------|-------|\n| `name` | Optional; unique per user. Duplicate → 400. |\n| `path` | One of the alertable paths above |\n| `arguments` | Upstream body **minus timestamps**. Never include `start_timestamp` / `end_timestamp` (422). |\n| `interval_minutes` | ≥ 5 and a multiple of 5 |\n| `lookback_minutes` | Rolling window; defaults to `interval_minutes` |\n| `threshold` | Min matching items before delivery (default 1) |\n| `receivers` | 1–2 targets; duplicate targets rejected |\n\n### Receivers\n\n| Type | Config |\n|------|--------|\n| `email` | `{ \"type\": \"email\" }` — delivers to the verified account email |\n| `telegram` | `{ \"type\": \"telegram\", \"chat_id\": \"…\" }` — start the Ultralayer alerts bot first |\n| `webhook` | `{ \"type\": \"webhook\", \"url\": \"…\", \"headers\"?, \"body_wrap_key\"?, \"body_wrap_as_string\"?, \"body_extra\"? }` — public http(s) only |\n\nCanonical envelope: `{ \"name\": \"<alert name>\", \"response\": <exact upstream JSON> }`. Email/telegram always get that envelope. Subject: `ULTRALAYER ALERT: {name}`.\n\n`create_alert` immediately calls the endpoint and delivers a **sample** to every receiver before persisting.\n\n#### Webhook body shaping\n\nUse these when the receiving API rejects an arbitrary JSON body and requires a fixed envelope. Structured merge only — no templating.\n\n| Field | Role |\n|-------|------|\n| `body_wrap_key` | Place the envelope under this key. One level of dot-separated nesting (`variables.PAYLOAD` → `{\"variables\": {\"PAYLOAD\": …}}`). |\n| `body_wrap_as_string` | JSON-encode the envelope to a string before placing it. Requires `body_wrap_key`. |\n| `body_extra` | Static keys merged into the top level of the body. Values must be string / number / boolean / null. |\n\nExamples:\n\n```json\n{\n  \"type\": \"webhook\",\n  \"url\": \"https://api.example.com/hooks/ingest\",\n  \"headers\": { \"Authorization\": \"Bearer …\" },\n  \"body_wrap_key\": \"client_payload\",\n  \"body_extra\": { \"event_type\": \"ultralayer_alert\" }\n}\n```\n→ `{ \"event_type\": \"ultralayer_alert\", \"client_payload\": { \"name\": \"…\", \"response\": … } }`\n\n```json\n{\n  \"type\": \"webhook\",\n  \"url\": \"https://ci.example.com/api/v4/projects/1/trigger/pipeline\",\n  \"body_wrap_key\": \"variables.PAYLOAD\",\n  \"body_wrap_as_string\": true,\n  \"body_extra\": { \"token\": \"…\", \"ref\": \"main\" }\n}\n```\n→ `{ \"token\": \"…\", \"ref\": \"main\", \"variables\": { \"PAYLOAD\": \"{\\\"name\\\":…}\" } }`\n\nArbitrary-JSON receivers (Zapier, Make, n8n, custom endpoints) need none of these fields.\n\n---\n\n## Delivery behavior\n\nEach run checks a rolling lookback window and never re-sends data already delivered. The alert fires only when at least `threshold` new items match. Attempt outcomes (`delivered`, `no_data`, `below_threshold`, `endpoint_error`, `delivery_partial`, `delivery_failed`) and recent deliveries are visible via `get_alerts`. If all receivers fail, the same data is retried next run.\n\nThere is no update-alert endpoint. Changing filters = delete + recreate.\n\n---\n\n## Workflow\n\n1. Prototype filters with the underlying endpoint until results look right.\n2. `create_alert` with those arguments (no timestamps) + receivers + interval. Expect a sample delivery.\n3. `get_alerts` to confirm status and early attempts.\n4. `execute_alert` to force a test run. `deactivate_alert` / `activate_alert` to pause/resume.\n5. `delete_alert` when done. Prefer pause over delete if the config may be reused.\n\n---\n\n## Limitations\n\n- Poll-based (minimum 5-minute cadence), not push-on-insert.\n- Only the alertable paths listed above.\n- Max 2 receivers; email is account-bound.\n- Webhooks must be public.\n- Webhook `headers` are count- and size-capped, and framing, routing and provenance headers (`Host`, `Content-Type`, `Content-Length`, `User-Agent`, `X-Forwarded-*`, …) are rejected. `Authorization`, `Cookie` and custom `X-` headers are fine.\n- Webhook `body_extra` and `body_wrap_key` are count-, size- and character-capped — see the OpenAPI schema for exact limits. Values are scalars only, and a field name containing a literal `.` cannot be targeted by `body_wrap_key`.\n- Create always sends a sample — warn before creating noisy webhooks.\n- No patch API for existing alerts.\n\n---\n\n## FAQ\n\n**Q: Is this more expensive than calling the API myself on a cron?**  \nA: Same underlying pricing; you gain dedupe, thresholding, multi-channel delivery, history, and managed scheduling.\n\n**Q: Why can’t I set `start_timestamp` in arguments?**  \nA: The alert owns the rolling window. Including timestamps → 422.\n\n**Q: Why did create email me immediately?**  \nA: Receiver verification delivers a real sample by design.\n\n**Q: `no_data` every 15 minutes — broken?**  \nA: Healthy. The window had zero matches. Check `deliveries` for real fires.\n\n**Q: How do I change an alert’s filters?**  \nA: There is no patch. Pause or delete + recreate.\n"
}