Direct HTML Artifacts API
Create and revise private static HTML artifacts without invoking an LLM or adding an API page. Routes begin at /v1/agents/{agentId}/html-pages.
Scoped authentication
Generate a dedicated key from the agent's Settings → HTML Artifacts section. Use only Authorization: Bearer YOUR_KEY; query-string keys are rejected. HTML pages and artifacts use html_artifacts:read, html_artifacts:write, html_pages:create, and optional html_artifacts:share. Asset lifecycle scopes are documented separately in Managed Assets.
Resources
| Resource | Operations |
|---|---|
| HTML pages | List, create |
| Artifacts | List, create, ID read/update, externalId lookup/upsert |
| Immutable revisions | List, read, append, restore as a new revision |
| Managed image references | Embed an existing higantic-asset reference in sanitized HTML |
| Stable visibility | Read private/public state and explicitly publish or unpublish the current revision URL |
| Pinned links | Create, list, revoke, and rotate immutable capability links |
Private by default sharing
Artifacts default to private and creation or upsert never publishes them. The opt-in html_artifacts:share scope can publish the stable /p/ARTIFACT_ID URL, which follows the current revision until made private. Visibility updates require the latest artifact version and emit an event only when the state changes.
Publishing requires a current revision and at most 100 managed images. Once public, replacing the current revision through append, restore, or HTML upsert also requires html_artifacts:share so write-only keys cannot change live public content.
Pinned /s/SHARE_TOKEN capability links are separate: each preserves one immutable revision, may expire, and remains active if stable visibility becomes private. The complete capability URL is returned only when created or rotated. Stable and pinned pages use strict sanitization, proxied same-agent images, noindex, and no-store policies without wildcard CORS.
Safe links and images
Artifact links must be absolute HTTPS URLs without credentials and always open in a new tab with no opener or referrer. Managed images use an existing higantic-asset://ASSET_ID. Create and manage that reference through the separate Managed Assets workflow.
Stable keys and idempotent creation
Artifacts may have an immutable page-unique externalId for deterministic lookup and upsert. Page and artifact create requests accept Idempotency-Key; exact durable replays return HTTP 200 and conflicting reuse returns 409 idempotency_conflict.
Conflict-safe updates
Conversational writes plus API append, restore, and external-ID upsert requests include expectedCurrentRevision. Metadata PATCH and external-ID upsert also include the returned expectedArtifactVersion. Stale content returns 409 revision_conflict; stale metadata returns 409 artifact_version_conflict. Read and reconcile before retrying.
Limits
HTML source is limited to 250 KiB and 100 revisions per artifact. Each key allows 120 requests per minute, including no more than 30 writes. Responses are private, use coded JSON envelopes, include a request ID, and are never cached.