API Conventions

Entry point and credential types

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

Grants, access tokens, and refresh cookies aren't interchangeable. Clients use the object identifiers and authorizations returned by the API—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 won't run unchanged in Node.js without a base URL. Pass a token from the actual authentication flow; there's no need to copy an HttpOnly cookie. Keep returned file information in your controlled environment.

Encoding and pagination

Use the UUIDs returned by the API 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 the 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 there's 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. Don't generalize this to every POST. When you're unsure whether a request succeeded, inspect the current state first and follow that endpoint's retry contract.

Status and reporting

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

When reporting an issue, include the method, a credential-free path shape, status, and time. Don't include Authorization, Cookie, share tokens, codes, or full user records.