# 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. **Give the user the `managedUrl` from that response and ask them to open it.** A created
   display is a profile, nothing more: it stays `offline` and shows nobody anything until a
   browser opens one of its URLs. `managedUrl` turns whatever browser opens it into that
   screen, so the phone in their hand will do. Skip this step and the next one succeeds
   against a screen that does not exist, you report content delivered, and the user sees
   nothing anywhere.
6. Deliver content with HTML.
7. 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
  - `display_setup`: everything in `content_only`, plus connecting a new screen by code (`pair_by_code`) or creating one (`create_display`). Ask for this when the user has no screen yet.
  - `admin`: full management — create, rename, delete, lock, unlock, claim, configure displays, rebind hardware, 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` — keyword search over agentView resources (docs, account, displays, API catalog)
- `fetch` — fetch one agentView resource by `agentview://` URI
- `search_public_apis` — curated free-API catalog for live data in display HTML (`list_categories: true` for the category menu)
- `search_store_templates` / `list_store_categories` / `get_store_template_details` / `get_store_template_content` — browse the template store
- `get_agent_artifact` — bot-onboarding artifact of a template (`slug` = raw; `display_id` = substituted, needs auth)

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

- `get_account` — account info, display quota, plan details
- `list_displays` — displays the user can access (`org_id` for an organization's displays; `response_format: "detailed"` for runtime facts)
- `get_display` — display details; `response_format: "detailed"` adds browser/runtime capabilities, connectivity limits and full content state
- `get_display_preview_url` — short-lived signed link showing what a display presents right now
- `read_display_html` — read raw HTML source of a display (windowed via `offset`/`max_bytes`)
- `send_html` — push HTML to a display (`slot: "idle"` sets the default/fallback content; idle needs admin)
- `send_url` — load a web page by URL on a display via iframe (`slot: "idle"` for fallback)
- `test_display_content` — dry-run validator for generated HTML, no display touched
- `broadcast_content` — send HTML to many displays: `display_ids`, `all: true`, or `include_category_ids` (+`include_descendants`, `dry_run`)
- `clear_display` — reset display to idle/default state
- `list_display_categories` — list the categories the user can manage (with hierarchy)
- `manage_display_category` — create or rename a category (`action: create | rename`)
- `assign_display_categories` — set category membership (`mode: replace | add | remove`)
- `list_organizations` — list organizations the user belongs to
- `get_organization` — organization details; `response_format: "detailed"` adds member and display lists
- `get_license_info` — license allocation overview (personal, per-org, free)
- `upload_asset` / `list_assets` / `get_asset` / `update_asset` / `delete_asset` — asset inventory for display HTML
- `set_data_slot` / `get_data_slot` / `list_data_slots` / `delete_data_slot` — mutable JSON slots displays fetch live
- `get_storage_usage` — storage pool snapshot; with `slug` also which displays reference that slot
- `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)

Display setup MCP tools (require `display_setup` or `admin` scope; connectors receive `mcp:display.setup` on connection):

- `create_display` — the default way to a first screen: create it and hand the user its `managedUrl` to open on a device they already have, the phone in their hand will do (`org_id` creates it inside an organization). This asks them to walk nowhere.
- `pair_by_code` — when the user is already standing at a screen showing a 6-character code from https://display.agentview.de (a TV, a wall panel, a kiosk): read the code and pair with it, which binds that hardware permanently. No app is needed, and no name; rebinding an existing display with `target_display_id` requires `admin`.

Admin MCP tools (require `admin` scope):

- `delete_display` — permanently delete a display
- `configure_display` — all display settings in one tool: rename (`name`), lock/unlock (`locked`), privacy mode, embed-origin allowlist (`origins`), hardware permissions (camera, microphone, geolocation), language, cursor, badge, watermark
- `claim_display` — adopt an unclaimed guest/pending display
- `manage_licenses` — premium licenses (`action: allocate | assign | unassign`)
- `create_organization` — create a new organization
- `configure_organization` — rename and/or set network policy + whitelist
- `delete_organization` — permanently delete an organization
- `manage_org_member` — membership (`action: invite | set_role | remove`)
- `remove_display_from_org` — remove a display from an organization
- `set_display_grant` — grant or revoke a user's access to a display (`action: set | remove`)
- `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`; ask for `display_setup` when the user needs a screen, and for `admin` only to rename, delete or rebind.
- If the user wants a visual result, generate the final HTML yourself instead of asking them to write markup.
- For a first screen, use `create_display` and give the user the `managedUrl` to open on a device they already have. That is the shortest path to something visible and it sends nobody looking for hardware. Only when they are already standing at a screen showing a 6-character code from https://display.agentview.de should you read that code and use `pair_by_code` instead. 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` (add `response_format: "detailed"` for the full content state) 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).