# Public links and visitor identity

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

Public Web apps provide conversations for anonymous visitors within the publication record's allowed scope. Publication tokens, visitor sessions, and signed-in users' product credentials serve distinct purposes.

<span id="prepare"></span>

## Before you call this API

Historical `/api/v1` strings in internal/frontend source are not deployment URLs. `WEBAPP_SHORT_CODE` is the link's 22-character short code. `AGENT_ID` and `WEBAPP_TOKEN` come from the publication link or resolve result; `WEBAPP_SESSION` comes from the session response. Examples use placeholders; do not put real credentials in maintenance records.

1. For `?k=...` links, submit `k` to resolve for `agent_id`, then use the short code as `t`. Legacy links use `webapp` and `t`; do not mix the two input forms.
2. Create a session on the first visit. Save `session_token` and `expires_in`. Later data requests use query parameter `s`, whereas refresh uses JSON field `session`.
3. Create a conversation with the same identity and save `data.id`. Messages, events, attachments, feedback, and MCP App operations continue to carry the current link and identity and reference their own conversation/task.
4. On return visits, refresh a still-valid session. Create a new identity only after confirmed invalidation. Preserve the identity and retry on dependency failures.

These handlers do not use product PATs, login Cookies, or CSRF parameters as visitor credentials. Gateway cross-origin and Cookie policies still require environment checks; handlers do not establish online policy.

## Lifecycle

sessions have a fixed 604800-second validity. Refresh issues new credentials for the same visitor; old credentials remain usable until their own expiry. Creating another session establishes a new visitor who cannot list the old identity's conversations.

session signatures bind publication Workspace, agent, and visitor identity, not directly the link token. After link rotation, the old link fails admission. If a new link is obtained while the original session remains valid, the session has not necessarily been cryptographically revoked. Disablement/rotation is revalidated on subsequent public requests and stream rereads; it does not immediately cancel already admitted background tasks.

The same agent has independent publication records in different Workspaces. Public conversations must belong to this visitor and target agent, have purpose=webapp, and be active. Archival also denies public messages, events, feedback, and task artifacts. Publisher access to management history uses separate APIs.

New sessions bind the publication record's creation generation. A deleted/recreated publication cannot inherit an earlier generation's identity. Old-record compatibility and dependency failures retain distinct errors. resolve checks link/display facts only; it does not establish an active agent, executable publication identity, or successful model tasks.

<span id="errors"></span>

## Errors and identity handling

Ordinary success uses numeric `code=0` and `data`; errors use `code/message`. Handle downloads, previews, and A2A streams according to their own response types.

| HTTP/code | Meaning and handling |
| --- | --- |
| 404 / 3 | Public admission unavailable, including mismatched link, session, conversation, or task bindings. Does not establish global object absence. |
| 404 / 16 | The matching link is disabled; retaining the saved visitor identity is appropriate. |
| 404 / 17 | Refresh confirms an invalid session. A new identity will not have the old identity's history. |
| 400 / 2 | Correctable input, including title, feedback, and file parameters. |
| 409 / 2 | Conflicts such as a busy conversation; not a missing object. |
| 429 / 18 | Insufficient shared publication upload budget. |
| 500 / 1 | Storage or runtime dependency failure. Retain visitor identity rather than masking failure by creating a new session. |

Previews also use 415, 413/19, and 422/20. MCP Apps additionally use 400, 404, 409, 503/15, and other results. A2A may return JSON-RPC errors before opening a stream; afterward, inspect error frames rather than HTTP status alone.

The permission specification retains old descriptions of all failures as 404 and refresh failure as code3. These disagree with current handler/service and actual frontend branches;
