[Epic 953][Stage I][chat-api] Retain established read views and selected DELETE routes; block writes

[think-in-universe]

Parent epic: nearai/cloud-api#953
Parent stage: nearai/cloud-api#954
Target date: Sep 1

Goal

Keep every existing Private Chat read endpoint available during Stage I for the migration/export window, along with four established session-authenticated DELETE routes. Retire stateful writes without changing the existing access model of any retained read.

The account-deletion flow in #380 remains a separate exception: DELETE /v1/users/me continues to enqueue its existing worker, which uses Cloud #943's retained workspace-scoped Conversation/File resource DELETE routes before local finalization.

Retained reads

All responses below send Cache-Control: no-store.

Surface	Existing retained routes	Existing access behavior
Conversation	GET /v1/conversations GET /v1/conversations/{conversation_id} GET /v1/conversations/{conversation_id}/items	The list is session-authenticated and owner-scoped. Detail/items preserve their existing optional-auth owner/share/public ACL: anonymous callers may read only public shares.
Sharing	GET /v1/conversations/{conversation_id}/shares GET /v1/share-groups GET /v1/shared-with-me	Existing session authentication and authorization semantics.
Files	GET /v1/files GET /v1/files/{file_id} GET /v1/files/{file_id}/content	Existing session authentication and caller/ownership checks.

These are existing views, not a new Chat API export endpoint. In particular, Chat API does not add a public POST /v1/conversations/batch or a new Cloud Conversation-list API; its existing owner-scoped Conversation list may use Cloud's retained batch view internally.

Retained DELETE routes

The following existing session-authenticated routes remain available with their current authorization semantics and Cache-Control: no-store:

• DELETE /v1/conversations/{conversation_id}
• DELETE /v1/files/{file_id}
• DELETE /v1/conversations/{conversation_id}/shares/{share_id}
• DELETE /v1/share-groups/{group_id}

Retired stateful writes

Every other stateful write returns authenticated 410 Gone with Cache-Control: no-store. This includes creation/update, item creation, file upload, share/share-group creation or update, clone/copy, both POST and DELETE pin, both POST and DELETE archive, unsupported methods, and unknown descendants. Retired operations must not forward a mutation to Cloud or write local Private Chat state.

Responses

POST /v1/responses remains a stateless/no-store proxy. It does not create response history, inject author metadata, force store: true, or track a Conversation locally. For client-managed custom function calls and matching function_call_output replay, Chat does not create a replacement transcript shape, reorder the supplied tool/input items, or execute tools; it forwards the normalized request to Cloud.

Cloud owns public Responses tool-schema validation. Unsupported Responses built-in or remote-MCP tool/input shapes receive Cloud's normal 400; this is distinct from the separate root POST /mcp proxy, which remains outside the Responses path.

Out of scope

• A new export endpoint, Cloud Conversation-list endpoint, schema/table migration, retention purge, or historical-data cleanup.
• Removing the temporary views, their service/repository wiring, or the Private Chat frontend. Those are Stage III work under [Epic 953][Stage III][chat-api] Remove stateful proxy surfaces and runtime wiring #377 after the export window.
• Changing or retiring the established account-deletion lifecycle. Any such change requires separate approval.

Acceptance criteria

• Every retained read preserves its existing auth/ACL semantics and is no-store.
• The four listed DELETE routes retain their existing authorization semantics and are no-store.
• All other stateful writes, including pin/unpin and archive/unarchive, are 410 Gone/no-store.
• DELETE /v1/users/me and its established worker remain functional through Cloud's retained resource DELETE routes.
• OpenAPI/docs advertise the retained reads and four DELETE operations, but omit retired writes.

[hanakannzashi]

@ironloopai help

[ironloopai]

⌨️ IronLoop command · Help

Available in this issue.

Command	Result
@ironloopai help	Show this command guide.
@ironloopai implement	Implement the issue and open a draft pull request.
@ironloopai list	Show recent Runs for this issue.

Example with instructions

@ironloopai implement

Keep the public API unchanged.

[hanakannzashi]

Stage I clarification — owner-only views

The retained export surface is now deliberately narrower: only the authenticated owner Conversation and File views listed in this issue remain temporarily available with Cache-Control: no-store.

Sharing is not needed for export. Every sharing namespace route, including GET /v1/conversations/{conversation_id}/shares, GET /v1/share-groups, and GET /v1/shared-with-me, is session-authenticated 410 Gone/no-store; optional-auth/public shared Conversation reads are closed as well.

Responses remains a stateless proxy with unchanged client-managed function replay, while Cloud owns built-in/MCP tool validation. Final removal of the retained owner views and their wiring remains Stage III work under #377.

[hanakannzashi]

Correction to the earlier Stage I clarification

Stage I retains four existing session-authenticated DELETE routes:

• DELETE /v1/conversations/{conversation_id}
• DELETE /v1/files/{file_id}
• DELETE /v1/conversations/{conversation_id}/shares/{share_id}
• DELETE /v1/share-groups/{group_id}

All other stateful mutations—including both pin/unpin and archive/unarchive—and every sharing operation other than the two sharing DELETE routes remain 410 Gone with Cache-Control: no-store. The temporary owner-only read views and stateless Responses contract are unchanged.