# 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=...`
   - 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)
   - 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|unassign-license`
   - 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` 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}`

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

## 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.

## 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
- `get_pricing` — plan pricing, features, upgrade options

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_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)
- `get_billing_url` — link to billing page for purchasing licenses

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
- `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 and content delivery confirmations.