# Control the display from any agent

Base URL: https://eink.pilipia.us

Import https://eink.pilipia.us/agent-openapi.json into an agent that supports OpenAPI.
The full contract, with administrator and device operations, is /openapi.json.
The API uses normal HTTP and JSON. It does not depend on a Muse or Hermes SDK.

## Connect an agent

1. Get a separate agent key from the administrator.
2. Store the key in the agent's secure credential store.
3. Send the key in the Authorization header: Bearer followed by the key.
4. Read GET /api/capabilities and GET /api/display.
5. Submit a display with PUT /api/display.
6. Read /api/display again. Check the intended device's rendered_revision.

A successful write confirms storage. It does not confirm a draw on a phone.
An online device polls every 30 seconds while its display is open.
An acknowledgement confirms one visible frame, not every frame in a sequence.

## Generate the full interface

Use type html to generate a full page. You can choose its layout, text, shapes,
spacing, font, and responsive CSS. Inline SVG is supported. The host converts
the result to black and white. There is no fixed tile count in this mode.

Example request body:

```json
{
  "type": "html",
  "title": "Today",
  "html": "<style>main{display:grid;place-content:center;height:100vh}h1{font-size:8vw}</style><main><h1>MAKE TODAY COUNT</h1><p>Choose one useful action.</p></main>"
}
```

HTML is static. Scripts, event handlers, forms, external resources, animated
images, and continuous CSS or SVG animation are not supported. Use a sequence
of two to six html, dashboard, or image frames for slow animation. Frame
intervals range from 10 to 3600 seconds in steps of 10. The default is 30.
The display checks frame changes every 10 seconds. A frame can start late by
up to 10 seconds. A static frame is not loaded again on every poll.

An html field can contain at most 24000 characters. A normalized screen can
contain at most 30000 UTF-8 bytes. The entire request is limited to 32768 bytes.
These limits apply to all frames together. Use inline SVG for shapes and charts.
HTML image resources are disabled. Use the image display type for public HTTPS
PNG/JPEG files. That type checks image size and dimensions before decoding.

Native dashboard mode supports one to three text, countdown, life_weeks,
or image tiles. Omit the life calendar birth_date to use the private Android
setting. A browser cannot read that private setting. Choose horizon_years 80
or another value from 20 to 120. Each calendar year contains 52 week dots.

## Use multiple agents

Each agent can replace all display content, save layouts, and restore history.
It cannot create credentials, revoke displays, or read private Android settings.
Use one key per agent so you can revoke one key without stopping other agents.
The administrator can create up to 32 separate agent keys.

To avoid overwriting a newer update, send the revision from GET /api/display
in the If-Match header on a display write. A stale revision returns 409.
Without that header, the latest successful write wins.

## Read the current display on the website

Open https://eink.pilipia.us. Paste an agent key into the masked credential
field. Select Show current display. The page fetches the current command and
checks for updates every 30 seconds. Double tap the display to return to setup.
The credential stays in browser memory for this session. It is not in the URL.
To register the browser as a display, use a one-time pairing code instead.
An agent preview does not send a device render acknowledgement.

The site and API do not publish private display content to anonymous visitors.

## Muse

Create a Custom Connector named E-Ink Display. Import /agent-openapi.json.
Use Muse's Secure Credentials Store for the agent key. Ask Muse to read status,
generate a full page, submit it, and confirm the phone's rendered revision.
The API is ready for that test only after deployment and phone pairing.
Muse connector creation is an account action. A generic API test does not prove
that Muse has used the connector.

## Hermes and other agents

Configure an HTTP/OpenAPI tool with the base URL and secure bearer credential.
Do not put credentials in prompts, source files, query strings, or logs.
This project does not change any Hermes profile or memory file.

## Keep the display on

Open the cloud display in Android. The app keeps the screen on while that
display is open. Android can still turn it off after a power-button press.
An LCD/OLED display consumes power even when its picture does not change.