documents

GET /api/admin/accounts/:sub/cloud/documents?cursor&limit[&content=1]: the account's own documents, newest change first (metadata only).

Caller and authorization

Staff cookie session; permission cloud.read. First request also needs a reason to unlock the account/organisation for 15 minutes; content=1 has an additional owner/support and step-up gate.

This is the private staff console on https://admin.handwrites.io. A personal API key, organisation token, student login or isolated app-testing credential does not authenticate this route.

Request contract

Location	Name	Required	Meaning
path	`sub`	Yes	Use the ID from an authorized staff response; source validators reject malformed IDs.
query	`cursor`	Conditional / optional	{"type":"string"}
query	`limit`	Conditional / optional	{"type":"string","minimum":1,"maximum":100}
query	`content`	Conditional / optional	Requests unmasked titles, names, settings and emails. Requires owner/support, fresh step-up and audit. Never returns document text or file/audio bytes.
header	`X-Admin-Reason`	Conditional / optional	URI-encoded written audit reason; Cloud/billing may reuse a fresh target-specific session marker.

This operation does not define a JSON payload. Staff writes still require Content-Type: application/json and the session-bound CSRF header.

Response and failures

Success: 200. GET /api/admin/accounts/:sub/cloud/documents?cursor&limit[&content=1]: the account's own documents, newest change first (metadata only).

The wrapper returns {error:{code,message}} for CloudError failures, attaches Request-Id, and disables caching. Handle 401 by signing in; show role refusal for 403 forbidden, reauthenticate only for step_up_required, and collect a reason for 400 reason_required. A CSRF failure needs a current page/session token, not blind retries. Operation-specific 404/409/413/422/502/503 errors retain their status. Honor Retry-After on 429.

Usage notes

A reason unlock is target- and session-specific for 15 minutes. The audit entry must succeed before data is read. content=1 exposes authorized descriptive fields; it never grants a customer-document download or returns original document text.

Implementation contract

Source snapshot: admin/src/app/api/admin/accounts/[sub]/cloud/documents/route.ts. This reference describes the current working tree, not proof of deployment. The response service types and validators remain authoritative. The exact exported handler below makes conditional behavior reviewable. For helpers such as customer-routes or cloudRoute, see the shared API specification notes and the named service module.

/** GET /api/admin/accounts/:sub/cloud/documents?cursor&limit[&content=1]: the account's own documents, newest change first (metadata only). */
export const GET = cloudRoute<{ sub: string }>("documents", accountTarget, async (request, { viewer, params }) => {
  const query = new URL(request.url).searchParams;
  const page = await documentsOf(accountPrincipal(params.sub), { cursor: query.get("cursor") ?? undefined, limit: pageLimit(query.get("limit")) });
  return { items: page.items.map((document) => presentDocument(document, viewer)), cursor: page.cursor ?? null };
});

Do not use production customer data to test this operation. Use an authorized staff test account and a disposable target in an appropriate environment; email, deletion, role and credential mutations have real effects.

README — GET /api/admin/accounts/{sub}/cloud/documents

GET /api/admin/accounts/{sub}/cloud/documents#

Caller and authorization#

Request contract#

Response and failures#