# agentView Agent Instructions

agentView is a browser-based display delivery platform — there is NO native app to install. A display is any device with a web browser that opens https://display.agentview.de. Agents can create displays, discover existing ones, and push HTML or URL-based content to them.

Base URL: `https://agentview.de`

## Preferred integration paths

1. **REST API for custom agents**
   - Session flow: `POST https://agentview.de/api/v1/agent/session/request`
   - Status polling: `GET https://agentview.de/api/v1/agent/session/status?id=...`
   - Session info: `GET https://agentview.de/api/v1/agent/session/info` (current session + token claims)
   - Session activate: `POST https://agentview.de/api/v1/agent/session/activate` (called by the dashboard after the user approves)
   - Session deny: `POST https://agentview.de/api/v1/agent/session/deny` (called by the dashboard if the user rejects)
   - Account info: `GET https://agentview.de/api/v1/agent/me`
   - Pricing: `GET https://agentview.de/api/v1/agent/pricing`
   - Display management: `GET/POST/PATCH/DELETE https://agentview.de/api/v1/agent/displays`
   - Content delivery: `POST https://agentview.de/api/v1/agent/displays/{id}/content` (supports html and base64Html)
   - URL delivery: `POST https://agentview.de/api/v1/agent/displays/{id}/url`
   - Content state: `GET https://agentview.de/api/v1/agent/displays/{id}/content`
   - Read HTML source: `GET https://agentview.de/api/v1/agent/displays/{id}/html` (returns raw HTML for read-modify-write workflows; optional `?content_type=idle`)
   - Capabilities: `GET https://agentview.de/api/v1/agent/displays/{id}/capabilities` (resolved network mode plus concrete browser/runtime facts such as fetch, WebSockets, srcdoc, CSS support, browser version, known limitations)
   - Broadcast: `POST https://agentview.de/api/v1/agent/displays/broadcast` (send to multiple displays at once)
   - Display lifecycle: `POST https://agentview.de/api/v1/agent/displays/{id}/clear|default|lock|unlock|configure|claim`
   - Idle content: `POST https://agentview.de/api/v1/agent/displays/{id}/default` (supports html, or clears when omitted)
   - **Display categories (owner-scope CRUD):** `GET/POST https://agentview.de/api/v1/owner/display-categories`, `PATCH/DELETE https://agentview.de/api/v1/owner/display-categories/{categoryId}`. Per-display membership: `PUT https://agentview.de/api/v1/owner/displays/{profileId}/categories`. Bulk assign: `POST https://agentview.de/api/v1/owner/display-categories/bulk-assign`. Org-scoped equivalents under `https://agentview.de/api/v1/orgs/{orgId}/display-categories/...`. Categories are hierarchical (parent_category_id) and addressable via slug or path.
   - **Broadcast by category:** `POST https://agentview.de/api/v1/owner/displays/broadcast-by-category` (or `/api/v1/orgs/{orgId}/displays/broadcast-by-category`) pushes HTML to every display tagged with the given category slug(s); supports descendant inclusion and dry-run.
   - Organizations: `GET/POST https://agentview.de/api/v1/agent/organizations`
   - Organization lifecycle: `PATCH/DELETE https://agentview.de/api/v1/agent/organizations/{orgId}`
   - Organization displays: `GET/DELETE https://agentview.de/api/v1/agent/organizations/{orgId}/displays/{displayId}`
   - Member management: `PUT https://agentview.de/api/v1/agent/organizations/{orgId}/members/{userId}/role`, `DELETE .../members/{userId}`
   - Display grants: `PUT/DELETE https://agentview.de/api/v1/agent/organizations/{orgId}/displays/{displayId}/grants/{userId}`
   - License management: `POST https://agentview.de/api/v1/agent/displays/{id}/assign-license` and `POST https://agentview.de/api/v1/agent/displays/{id}/unassign-license`
   - Pair by code (REST): `POST https://agentview.de/api/v1/agent/displays/pair-by-code` (server-side counterpart to the `pair_by_code` MCP tool)
   - Org connectivity: `POST https://agentview.de/api/v1/agent/organizations/{orgId}/connectivity` (REST counterpart to `set_org_connectivity`)
   - License info: `GET https://agentview.de/api/v1/agent/license-info`
   - Billing: `GET https://agentview.de/api/v1/agent/billing-url`
   - **Real-time events (SSE):** `GET https://agentview.de/api/v1/agent/events` — streams `display_online`, `display_offline`, `content_delivered`, `content_cleared`, and `data.changed` events as Server-Sent Events
   - **API keys:** `POST/GET/DELETE https://agentview.de/api/v1/agent/api-keys` — create, list, and revoke long-lived API keys for server-to-server integration
   - **Public API catalog:** `GET https://agentview.de/api/v1/agent/public-apis?query=...&category=...&cors_only=...&limit=...` — search 600+ free, no-auth public APIs for embedding live data (weather, news, images, sports, finance, etc.) in display HTML via fetch()
   - API categories: `GET https://agentview.de/api/v1/agent/public-apis/categories`
   - API detail: `GET https://agentview.de/api/v1/agent/public-apis/{slug}`

## Owner controls (REST-only, no MCP tools)

These endpoints belong to the human owner of an account. They run on the dashboard cookie session, not Bearer tokens, so an agent cannot call them directly. They are documented here so an agent understands the surrounding contract and can surface meaningful guidance when a normal write hits a related error.

- **Approval mode**: when an owner enables approval mode for a display via `PUT https://agentview.de/api/v1/owner/displays/{id}/approval-mode`, every subsequent agent push is staged instead of going live. The owner accepts or rejects pending content via `POST https://agentview.de/api/v1/owner/displays/{id}/pending/accept|reject`. `POST .../rollback` swaps the live content for the previous version. Read state: `GET .../approval-state`. While approval is active, an agent that calls `send_html` / `send_url` will receive a normal 200 response, but the content state is `pending` until the owner approves.
- **Source-lock**: an owner can bind a display exclusively to one API key via `PUT https://agentview.de/api/v1/owner/displays/{id}/source-lock`. Agent calls from a different key or session receive `403 display_source_locked`. Read state: `GET .../source-lock`. The dashboard cookie session always bypasses the lock so the owner does not lock themselves out.
- **Activity audit**: append-only log of who pushed what content via which key, plus approval/lock/webhook events. Owner reads `GET https://agentview.de/api/v1/owner/activity-audit`. Admin reads `GET https://agentview.de/api/v1/admin/activity-audit`. Each entry carries actor, auth method, action, target type / id, org id, truncated IP, user agent, and a metadata dictionary.
- **Webhooks**: HMAC-SHA256-signed outbound notifications. Owner manages via `GET/POST https://agentview.de/api/v1/owner/webhooks`, `DELETE https://agentview.de/api/v1/owner/webhooks/{id}`, `PATCH https://agentview.de/api/v1/owner/webhooks/{id}/active`, `POST https://agentview.de/api/v1/owner/webhooks/{id}/test`. Event patterns: `display.*` (online/offline), `display.content.*` (delivered/cleared), `display.approval.*` (pending/approved/rejected/rolled_back), or `*` for everything. The signing key is shown only once at create time. Connections to internal network addresses are blocked.

2. **Modern MCP for tool-based clients**
   - Preferred endpoint: `POST https://agentview.de/mcp`
   - Discovery:
     - `GET https://agentview.de/.well-known/oauth-protected-resource/mcp`
     - `GET https://agentview.de/.well-known/oauth-authorization-server`
   - Authorization:
     - `GET https://agentview.de/authorize` with PKCE
     - `POST https://agentview.de/token`

3. **Direct send path for tokenized display links**
   - `POST https://agentview.de/send/{displayId}?token=...&duration=300`
   - Use this for demos, badge screens, reception displays, or any short-lived push where a tokenized display URL already exists.

## Recommended agent workflow

1. Check whether you already have a valid Bearer token.
2. If you do, call `GET https://agentview.de/api/v1/agent/me`.
3. List displays with `GET https://agentview.de/api/v1/agent/displays`.
4. If the user has no display and your scope allows it, create one with `POST https://agentview.de/api/v1/agent/displays`.
5. Deliver content with HTML.
6. If you do not have a token, start either the REST session flow or the MCP OAuth flow.

## Authentication rules

- Never ask the user for passwords.
- For REST agents, use `POST https://agentview.de/api/v1/agent/session/request` and guide the user to the returned `loginUrl`.
- For MCP clients, use OAuth 2.1 Authorization Code with PKCE via the well-known metadata documents.
- For server-to-server integrations, use API keys: `Authorization: Bearer avk_...` or `X-API-Key: avk_...`. Create keys via `POST https://agentview.de/api/v1/agent/api-keys` or the `create_api_key` MCP tool.
- Supported scopes are:
  - `content_only`: send content, list and inspect displays, view organizations
  - `admin`: full management — create, rename, delete, lock, unlock, claim, configure displays, manage idle content, manage organizations

## Try it without claiming a display

Send to the magic display id `test` to validate your request shape, auth, and HTML without persisting or broadcasting:

```bash
curl -X POST https://agentview.de/api/v1/agent/displays/test/content \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"html":"<h1>Hello agentView</h1>","description":"smoke test"}'
```

The response carries `simulated: true` so your client can recognise the dry-run.

## Content delivery rules

- **Always send a single HTML file** with CSS and JavaScript. Only one file can be uploaded, but the HTML may reference external resources (CDN fonts, images, scripts, APIs, iframes). The display renders this file in an iframe with full network access.
- Before generating complex HTML, inspect `GET https://agentview.de/api/v1/agent/displays/{id}/capabilities`. It returns concrete runtime facts for that exact display browser, including browser version, feature support booleans, and known limitations.
- **Visual quality matters.** The content appears on physical screens (TVs, kiosks, tablets) that real people look at. Produce polished, professional output: clean typography, balanced spacing, appropriate font sizes for distance reading, consistent color schemes, and smooth CSS transitions or animations where they add value. Think of each display as a digital signage screen — not a quick prototype.
- Always include `<meta charset="UTF-8">` and `<meta name="viewport" content="width=device-width, initial-scale=1">` in the HTML `<head>`.
- Design for full-screen display: use `100vw`/`100vh`, avoid scrollbars, and ensure content scales gracefully.
- Use `Content-Type: text/html; charset=utf-8` when sending raw HTML request bodies.
- If a display is currently idle, prefer sending useful content instead of waiting for manual confirmation.

## Content runtime contract

This is exactly where and how your published content executes. Do NOT guess it from the marketing pages.

- **Preview equals live.** The device renders content by loading the signed `contentUrl` (returned by `GET https://agentview.de/api/v1/agent/displays/{id}/content`) into a sandboxed iframe. That URL contains the word `preview` for historical reasons, but it is the real device render path: the dashboard preview and the physical device load the SAME url under the SAME policy.
- **Do not derive the policy from a root URL.** The root of the content host is the app shell and never serves content; its strict CSP is unrelated. The contract below is what your content actually runs under.
- **Content Security Policy (live):** `script-src * 'unsafe-inline' 'unsafe-eval' blob: data:`, `connect-src * data: blob:`, `img-src`/`media-src * data: blob:`, `style-src * 'unsafe-inline'`, `font-src * data: https:`, `frame-src *`. Allowed: inline scripts, `eval`/`new Function`, external CDN scripts over https, dynamic `import()` of `blob:`/`data:` modules, `fetch` to any origin, embedding iframes. There is no CSP-level restriction on external data sources.
- **Sandbox and origin:** the iframe is sandboxed WITHOUT `allow-same-origin`, so the document has an opaque (`null`) origin. Consequently `localStorage`, `sessionStorage`, cookies and IndexedDB are NOT available, and every `fetch` (even to agentView's own content host) is cross-origin and sends `Origin: null`. Any external API you call must allow CORS (the simplest is `Access-Control-Allow-Origin: *`). Write content that is self-contained and survives a reload with no client-side persistence.
- **duration:** optional integer seconds, range 1 to 86400, on the content, url and broadcast calls. Omit it, send `null`, or send `0` for indefinite (content stays until replaced or cleared). A positive value makes the display return to its idle screen after that many seconds. This is enforced on live displays.
- **Live data without re-pushing HTML:** write a Data Slot with `PUT https://agentview.de/api/v1/data/{slug}` and poll the public `readUrl` it returns from inside your content. That readUrl is served with `Access-Control-Allow-Origin: *`, so it works under the opaque origin. Prefer this player-plus-slot pattern over blob-based module loaders or re-sending the whole document.

## Example templates

agentView provides curated, high-quality example dashboards. **Before generating new dashboard content, review these examples to match their visual quality and design patterns.**

- **Catalog:** `GET https://agentview.de/examples/index.json` — returns metadata for all examples (title, description, category, tags, theme, fonts, features)
- **View an example:** `GET https://agentview.de/examples/{file}` — returns the full HTML source (e.g. `https://agentview.de/examples/baker.html`)

Available examples:

| ID | Category | Description |
|----|----------|-------------|
| `baker` | Gastronomy | Cafe & bakery menu with promotions and opening hours — warm glassmorphism, golden accents |
| `clinic` | Healthcare | Patient calling system with queue, doctor status, emergency info — light, trustworthy design |
| `kpi-dashboard` | Business | Agency mission control with KPIs, project progress, deadlines, team feed — dark neon style |
| `logistics` | Logistics | Warehouse control center with dock bay map, shipments, safety counter — industrial tech design |
| `weather-kalterherberg` | Smart Home | Live weather, forecast, air quality, news — elegant split layout with live API integration |
| `welcome` | Office | Executive reception with guest list, transit, cafeteria menu, WiFi — corporate glass design |

**How to use examples:**
1. Fetch `https://agentview.de/examples/index.json` to browse available templates by category or tags.
2. Fetch the HTML source of a relevant example to study its layout, CSS patterns, and design language.
3. Use the example as a quality baseline — adapt the design to the user's specific needs rather than copying it verbatim.
4. Match the example's level of polish: proper typography, balanced spacing, viewport-scaled units (`vw`/`vh`), glassmorphism effects, and professional color schemes.

## MCP tools

Public MCP tools (no authentication required):

- `create_auth_session` — start a new authentication session
- `get_auth_session` — poll session status
- `authenticate` — authenticate with a token
- `logout` — clear session identity
- `get_public_status` — server readiness, version, discovery URLs
- `search` — web search via integrated search engine
- `fetch` — fetch a URL and return its content

Authenticated MCP tools (require `content_only` or `admin` scope):

- `get_account` — account info, display quota, plan details
- `list_displays` — list all displays the user can manage
- `get_display` — full display details including live state, content, and hardware/UI settings
- `get_display_capabilities` — resolved browser/runtime capabilities for a display
- `get_display_content` — current content state, live preview link, idle content
- `read_display_html` — read raw HTML source code of a display
- `send_html` — push HTML content to a display
- `send_url` — load a web page by URL on a display via iframe
- `broadcast_content` — send HTML content to multiple displays at once
- `clear_display` — reset display to idle/default state
- `list_display_categories` — list the categories the user can manage (with hierarchy)
- `broadcast_to_categories` — push HTML to every display tagged with the given categories; supports `include_descendants` and `dry_run`
- `list_organizations` — list organizations the user belongs to
- `get_organization` — full organization details with members and displays
- `list_org_displays` — list all displays in an organization with live status
- `get_license_info` — license allocation overview (personal, per-org, free)
- `submit_feedback` — send the user's product feedback about agentView to an internal review queue (only when the user explicitly asks to share feedback, a request, or a complaint)

Admin MCP tools (require `admin` scope):

- `create_display` — create a new personal display (prefer pair_by_code first for physical screens)
- `rename_display` — change display name
- `delete_display` — permanently delete a display
- `lock_display` — prevent content changes
- `unlock_display` — allow content changes again
- `set_idle_content` — set or clear default idle content (HTML)
- `configure_display` — update hardware permissions (camera, microphone, geolocation) and UI settings (mouse cursor, badge overlay, watermark position)
- `pair_by_code` — ask the user to open https://display.agentview.de in any web browser on the screen (no app needed), then pair using its 6-character setup code
- `claim_display` — adopt an unclaimed guest/pending display
- `create_display_category` — create a new display category (optional `parent_category_id` for hierarchy)
- `set_display_categories_for_display` — set the full category membership of one display
- `bulk_assign_display_category` — add or remove a category on many displays at once
- `rename_display_category` — rename a category
- `assign_license` — assign a premium license to a display
- `unassign_license` — remove a premium license from a display
- `create_organization` — create a new organization
- `rename_organization` — rename an organization
- `delete_organization` — permanently delete an organization
- `invite_member` — create an invite link for an organization
- `update_member_role` — change a member's role in an organization
- `remove_member` — remove a member from an organization
- `allocate_licenses` — distribute premium licenses to an organization
- `create_org_display` — create a display within an organization
- `remove_display_from_org` — remove a display from an organization
- `set_display_grant` — grant a user access to a specific display
- `remove_display_grant` — remove a user's display access grant
- `set_org_connectivity` — set organization network policy and whitelist
- `create_api_key` — create a long-lived API key for server-to-server integration
- `list_api_keys` — list all API keys (metadata only, raw key is never shown again)
- `revoke_api_key` — permanently revoke an API key

## Operational guidance

- Prefer `content_only` unless display administration is truly required.
- If the user wants a visual result, generate the final HTML yourself instead of asking them to write markup.
- For first-time setup on real hardware, tell the user to open https://display.agentview.de in any web browser on the screen and share the 6-character code, then use `pair_by_code`. There is NO native app — agentView is purely browser-based.
- If the user already has a tokenized display URL, the direct `/send/{displayId}` path is often the fastest option.
- For modern tool-based clients, prefer MCP. For scripted service integrations, prefer the REST API.
- Use `get_display_content` to inspect what a display is currently showing before sending new content.
- Use `list_organizations` and `get_organization` to answer questions about team membership and organization displays.
- Use the SSE event stream (`GET /api/v1/agent/events`) instead of polling to monitor display online/offline status, content delivery confirmations, and data-slot mutations (`data.changed` fires whenever any slot the caller can read is created, updated, or deleted).