Image handling and share cards

Agreebase has two image-bearing artifact types:

• Document and signature identicons; deterministic visual fingerprints of a sealed record and of a finalized signer or witness, respectively. See Identicons for what they represent, how they're generated, and what they're safe to rely on; this page covers only their wire representation.
• A share card is a rendered PNG artifact intended for an authorized participant to share or download. It is not an identicon and is never exposed as ordinary public metadata.

Default response shape

REST and MCP agreement listing, retrieval, and verification responses use compact metadata by default. An identicon contains:

{
  "kind": "document",
  "digest": "sha256:...",
  "short_hash": "abid:12ab-34cd-56ef",
  "width": 266,
  "height": 154,
  "alt_text": "Document identicon AGR-... (abid:12ab-34cd-56ef)",
  "available": true
}

The default response contains no SVG bytes, data URI, storage path, or card download URL. Share-card metadata contains the filename, content type, dimensions, artifact hash, generation time, and available; it does not contain an internal storage path.

Requesting a visual representation

MCP tools that return image-bearing data expose visual_representation:

• metadata is the default and is appropriate when an agent needs to compare fingerprints, display accessible metadata, or keep context small.
• inline keeps the structured payload compact and adds MCP-native ImageContent. Use it when the host can display MCP images immediately.
• compatibility_data_uri deliberately places the legacy SVG data URI in the structured response. Use it only for a client that cannot consume native MCP image content.

The same compact payload is used for MCP structuredContent and the first text content block. Inline image bytes are carried only by a separate native image block, so an agent should not copy image data from the text block.

Share cards use a separate representation choice on get_agreement_card:

• url is the default and returns a short-lived, single-use download ticket.
• inline returns the PNG as native MCP ImageContent, without putting bytes in structured content.
• compatibility_base64 deliberately returns legacy base64 bytes in the structured payload.

Examples:

{"agr_reference":"AGR-...","visual_representation":"metadata"}

Use this for listing or checking a record. For a visual MCP-capable client:

{"agr_reference":"AGR-...","visual_representation":"inline"}

To retrieve a private card after participant authentication:

{"agr_reference":"AGR-...","representation":"url"}

Use representation="inline" only when the agent's MCP host is prepared to render an image block. Use compatibility modes only when an older client requires the legacy wire format.

Visibility

Public known-reference verification and public agreement responses may expose document-identicon metadata only when the record is sealed. They never expose signature identicons, card artifacts, storage paths, agreement bodies, or private participant metadata. Agreebase does not provide an identicon listing or enumeration endpoint.

MCP verify_agreement, including its inline representation, returns only the document identicon. MCP list_agreements likewise returns or inlines only the document identicon represented by each list item. It does not add party or signature images that are absent from the list contract.

Authenticated participant get_agreement views may expose the document identicon and permitted current signature-identicon metadata for its parties. Authenticated signature-execution reads expose the current caller's finalized signature identicon. Participant authorization uses the existing identity graph, so declarants, signers, co-signers, and witnesses retain the same access behavior as the corresponding agreement and signature APIs.

The visual fingerprint itself is not treated as a private agreement lookup. However, unauthenticated access is restricted to a caller-supplied known reference and sealed public metadata; it cannot be used to enumerate records or infer private participant data.

Share cards are stricter: only an authenticated, authorized participant may request one. Existing authenticated binary card routes retain their existing authorization. MCP card retrieval uses the already-authenticated MCP session and does not ask the user to authenticate again.

Share-card URLs

The URL returned by REST card-ticket issuance or MCP get_agreement_card:

• identifies only an opaque ticket, never an agreement reference or metadata;
• expires after five minutes by default, within the configured bounded TTL;
• succeeds only once after a successful artifact read;
• is redeemed atomically, so concurrent requests cannot both consume it;
• is removed from the ticket store after redemption or expiry by an hourly maintenance job;
• is returned with Cache-Control: no-store, Referrer-Policy: no-referrer, and content-sniffing protections.

Treat a ticket URL as a secret. Do not log it, put it in a prompt transcript, or persist it beyond the immediate download. A failed or expired redemption returns a generic not-found response and does not reveal whether a ticket was ever valid.