Publication records, links, and history¶
Management APIs modify publication records and read history only. Public visitor admission, session refresh, and calls use the public data plane separately.
First read and default state¶
Current agent creation may automatically create an enabled=true publication record. For older agents without a record, management GET first verifies a workspace/system definition exists, then creates an enabled=false record and token. Concurrent first reads read back the existing record.
GET can therefore have persistent side effects. Do not apply new-agent defaults to old objects. Enabling/disabling and rotation require an existing publication record. GET cannot create an orphan publication record for an unknown Agent.
Enable, disable, and rotate¶
PATCH requires an explicit boolean. Do not omit false to mean unchanged. Repeating the current enabled value succeeds without rewriting the record and retains token and timestamps; this does not refresh an old publishing identity.
Disabling retains the token, and reenabling restores the same link. Rotation replaces token/short code and updates last_rotated_at while retaining enabled. Rotation is not an idempotent retry returning the same token. If the result is unknown, GET the current link before proceeding.
The publishing identity saved when enabling comes from a snapshot of the current workspace owner. Rotation captures it again. Internal publisher fields are absent from the response DTO. Continued admission for old records or changed owners, and invalidation timing of open visitor sessions or ongoing streams, require the public session protocol and live-environment verification. Management PATCH success alone does not establish them.
History queries¶
Management reads Web application purpose conversations, messages, and feedback by Agent using agent.read privileges. It does not restrict results to visitors created by the currently signed-in administrator, nor hide history when a link is disabled.
Conversation status defaults to active; all includes active and archived. Message reads additionally verify the conversation belongs to the current Agent definition, has purpose=webapp, and is visible. All lists default to 50, maximum 200; negative offset becomes0. Stop using current totals and empty pages. These are not fixed snapshots across requests.
Errors and reading again¶
Management endpoints use numeric code/message: invalid parameters may return 400, missing objects/conversations404, denied privileges403, unavailable authorization dependencies503, and other errors follow their specific mappings. Site configuration uses separate string code/msg; do not reuse management error tables.
Business writes for enabling/disabling and rotation and operation-audit writes occur in separate subsequent transactions. Audit failures may return an error after the publication record changed. GET the record after an overall error or unknown response. Failure does not guarantee restoration of the original state.
Management operations currently accept no expected_version parameter. Internal comparison of the old token and creation time protects records but does not imply a client CAS field. Do not invent unregistered Web application DELETE, fixed-version publication, or upgrade operations.