Views API

List, push, refresh-request, and delete views, plus the view-events long-poll that closes the agent refresh loop.

All paths are relative to https://docs.aicomputercompany.com/api. Background: Views and the Dynamic views guide.

List views

GET /docs/:id/views

Response — 200: {"views": [...], "currentRevisionId": "rev_…"} — compare each view’s source revision against currentRevisionId to detect staleness.

curl https://docs.aicomputercompany.com/api/docs/doc_abc123/views

Push a view

POST /docs/:id/views

Body:

Field	Type	Required	Description
`kind`	string	yes	`"gantt"` \| `"coverage"` \| `"prompts"` \| `"digest"` \| `"custom"` \| any string.
`title`	string	no	Card header.
`payload`	JSON	yes	Kind-specific payload. For `custom`: `{"html": "<!doctype html>…", "title"?: "…"}` — `html` is required, a string, and ≤ 1 MB (400 otherwise).
`replace`	boolean	no (default `true`)	Upsert by kind. Pass `false` to keep several views of the same kind.

Response — 201: {"view": {…}}

# Push a custom HTML view (jq packs the file into the JSON payload)
curl -X POST https://docs.aicomputercompany.com/api/docs/doc_abc123/views \
  -H 'Content-Type: application/json' -H 'x-actor-id: agent_demo' \
  -d "$(jq -Rs '{kind: "custom", title: "Word count", payload: {html: .}}' < view.html)"

Request a refresh

POST /docs/:id/views/:viewId/refresh-request

Response — 200: {"ok": true}

Called by the app when a human clicks Refresh on a stale view (you can also call it yourself). It emits a refresh-requested event on the view-events stream so the owning agent can regenerate the payload.

Delete a view

DELETE /docs/:id/views/:viewId

Response — 200: {"ok": true}

View events (long-poll)

GET /docs/:id/view-events?since=0&timeoutMs=25000

Blocks until events newer than since arrive, or until timeoutMs elapses.

Response — 200:

{
  "events": [
    { "seq": 7, "type": "refresh-requested", "viewId": "view_…", "at": "2026-06-12T…" }
  ],
  "seq": 7
}

Event types: view-updated · view-deleted · refresh-requested.

Loop on this endpoint to close the refresh cycle — human edits → clicks refresh → you regenerate the view payload and POST it back:

SEQ=0
while true; do
  RES=$(curl -s "https://docs.aicomputercompany.com/api/docs/doc_abc123/view-events?since=$SEQ&timeoutMs=25000")
  SEQ=$(echo "$RES" | jq '.seq')
  echo "$RES" | jq -c '.events[] | select(.type == "refresh-requested")'
  # …regenerate and re-POST the view for each refresh-requested event…
done