API Conventions

Entry point and credential types

The public prefix is /api/v1 on your instance. Exact schemas are in the source's docs/openapi.yaml. Browsers use same-origin Nginx, not internal Core, database or Worker ports.

| Request | Authentication | | --- | --- | | Code request/verification, public catalogue, share/publication tickets | Endpoint-specific challenge, password and availability checks; no login token required | | Personal files, quota, share management, publication management | Authorization: Bearer <accessToken> | | Users, dashboard and notifications administration | Bearer identity plus server-side admin checks | | Upload parts and completion | Core-issued uploadGrant | | Object download | Core-issued single-use downloadGrant | | Refresh and sign-out | Same-origin refresh cookie, not a refresh token in the request body |

Grants, access tokens and refresh cookies are not interchangeable. Clients use returned object identifiers and authorizations, never manufacture grants or invoke private finalization callbacks.

A read-only post-login check

After signing in on your own instance, a controlled developer client can inspect files and quota using an existing accessToken. This function requests no code, modifies no file and prints no credential. Supply the token at runtime rather than embedding it in source.

async function inspectMyWebDrive(accessToken) {
  if (typeof accessToken !== 'string' || !accessToken.trim()) {
    throw new Error('An authenticated access token is required');
  }
  const read = async (path) => {
    const response = await fetch(`/api/v1${path}`, {
      headers: { Authorization: `Bearer ${accessToken}` },
      credentials: 'same-origin',
    });
    if (!response.ok) throw new Error(`Request failed: ${response.status}`);
    return response.json();
  };
  const [files, quota] = await Promise.all([
    read('/files?limit=20'),
    read('/quota'),
  ]);
  return {
    files: files.items,
    nextCursor: files.nextCursor,
    availableBytes: BigInt(quota.availableBytes),
  };
}

This is a same-origin browser example. It does not run unchanged in Node.js without a base URL. Pass a token from the actual authentication flow; it does not require copying an HttpOnly cookie. Keep returned file information in your controlled environment too.

Encoding and pagination

Use returned UUIDs for fileId, shareId and userId. Share tokens, publication slugs and fileIds are different identifiers. Apply encodeURIComponent to individual path segments and URLSearchParams to queries rather than concatenating unescaped input.

Byte counts are decimal strings; calculate with BigInt. Files, versions and public catalogue use nextCursor, while administrative user and notification lists use page numbers. Pass cursors unchanged in their original context and restart pagination after changing filters. A null cursor means no further page in that response, not that all future records have been obtained.

Do not retry every request

GET requests can be retried with appropriate backoff, but code requests, verification, refresh and share/publication tickets have side effects. Retrying a share ticket may consume another allowance; reusing a refresh token may revoke the session.

Upload intents use Idempotency-Key. Keep the same key and identical arguments when retrying the same operation; use a new key for a different operation. Do not generalize this to every POST. If success is uncertain, inspect current state first and follow that endpoint's retry contract.

Status and reporting

For 400 check parameters; 401 identity or grant; 403 administrator permission; 404 possibly deliberately hidden inaccessible resources; 409 state or uniqueness conflict; 413 upload-byte boundary; 429 limits; 503 temporary dependencies. The relevant feature page gives the precise meaning.

Report method, a credential-free path shape, status and time. Do not provide Authorization, Cookie, share tokens, codes or full user records. Ask Docs can explain the workflow.