Requests, responses and safe retries

1 · Transport, identity and validation

Use same-origin HTTPS in production. JSON request bodies use Content-Type: application/json; request properties are at the top level. The internal parser’s body.data is not a wire envelope. Do not send an extra {data:{...}} wrapper. Form login and binary upload chunks use their own content types.

Timestamps in document records are milliseconds. Drive revisions are opaque strings. A missing field and explicit null are different; preserve them. DocumentRecord, folder and canvas fields are defined in 10 Data Structure.

Required rebuild · Request and file limits

These are target limits for the rebuild, not a claim that the existing runtime enforces them. Reject non-identity Content-Encoding with HTTP 415. Cap the streamed request-body bytes before parsing/allocation or ticket acceptance and validate per-item sizes. JSON sizes are serialized UTF-8 bytes, including envelopes and escaping; raw binary chunk sizes count binary body bytes. Do not compare only parsed note-text length. Keep readable note text in the browser when a limit is exceeded; never truncate it silently.

The required normalized size error is {error:{code:"PAYLOAD_TOO_LARGE",message:"This request is too large.",retryable:false},maxBytes:8388608} with HTTP 413. Adapt this explicitly when interoperating with existing string errors; maxBytes is the limit of the failed boundary. Note content, filenames containing private data and credentials must not be echoed. An oversized pending note remains locally recoverable and exportable.

2 · Sign-in, connection and note-storage status

Synthetic active storage response

HTTP 200
Content-Type: application/json

{
  "active": true,
  "connected": true,
  "folderId": "drive-app-folder",
  "folderName": "FileLoveNote",
  "notesCount": 1,
  "migrationPending": false,
  "migrationStage": "active",
  "userKey": "0123456789abcdef0123456789abcdef"
}

Legacy browser import uses GET /api/local-first/bootstrap → {enabled:true,browserOnly:true,documents:[],migrationReceipt:string,noteFolders:[],media:[],exportedAt:number}, followed only after durable browser import by POST /api/notes/storage/browser-import with {receipt:string} → {ok:true}. Receipt mismatch gives 409. Active Drive middleware can reject the old bootstrap path with 409, so the rebuild must define and test migration ordering rather than assume every old route remains available in every state.

3 · Incremental note retrieval

POST /api/drive-notes is the Drive-mode pull. Send your confirmed revision map, including all locally known remote versions. The map is not a page offset. After each successful batch, retain unchanged content and merge the returned revision knowledge; repeat while hasMore is true. Render IndexedDB first.

A changed note in an incremental batch

POST /api/drive-notes
Content-Type: application/json

{
  "revisions": {
    "doc-example": "opaque-revision-before"
  }
}

HTTP 200
Content-Type: application/json

{
  "documents": [
    {
      "id": "doc-example",
      "title": "Research notes",
      "folderId": "note-folder-example",
      "content": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "My observations about the source file."
              }
            ]
          }
        ]
      },
      "createdAt": 1793000000000,
      "updatedAt": 1793000001000,
      "trashedAt": null,
      "driveRevision": "opaque-revision-a",
      "driveFileId": "drive-note-example"
    }
  ],
  "revisions": {
    "doc-example": "opaque-revision-a"
  },
  "hasMore": false,
  "removed": []
}

Old GET /api/drive-notes returns 409 with {error:string} asking the client to refresh. Do not build a new full-content polling protocol around it. The incremental contract requires active Drive mode; inactive storage is a browser-only state, not an empty remote dataset. Transport failures generally surface as 503 with a generic error, not a successful empty list.

4 · Batched note and folder changes

POST /api/drive-notes/push accepts three optional arrays, each defaulting to an empty array in the current implementation. Each array may contain at most 80 entries. Exceeding the cap creates a 413 error internally; a direct request’s outer catch currently often reports 503, while the station path preserves the processing status. Required rebuild: reject invalid top-level JSON and enforce count/byte limits before accepting a ticket, with explicit 400/413 responses.

One new version, one note deletion and a parent-folder operation

POST /api/drive-notes/push
Content-Type: application/json

{
  "station": true,
  "upserts": [
    {
      "id": "doc-example",
      "document": {
        "id": "doc-example",
        "title": "Research notes",
        "folderId": "note-folder-example",
        "content": {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "My observations about the source file."
                }
              ]
            }
          ]
        },
        "createdAt": 1793000000000,
        "updatedAt": 1793000001000,
        "trashedAt": null,
        "driveRevision": "opaque-revision-a",
        "driveFileId": "drive-note-example"
      },
      "baseDocument": {
        "id": "doc-example",
        "title": "Research notes",
        "folderId": "note-folder-example",
        "content": {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "My observations about the source file."
                }
              ]
            }
          ]
        },
        "createdAt": 1793000000000,
        "updatedAt": 1793000000000,
        "trashedAt": null,
        "driveRevision": "opaque-revision-a",
        "driveFileId": "drive-note-example"
      },
      "token": "queue-version-example"
    }
  ],
  "deletes": [
    {
      "id": "doc-remove-example",
      "token": "delete-version-example"
    }
  ],
  "folders": [
    {
      "key": "folder-op:000000000001",
      "id": "note-folder-example",
      "kind": "create",
      "body": {
        "name": "Sources",
        "parentId": "folder-notes"
      }
    }
  ]
}

HTTP 200
Content-Type: application/json

{
  "queued": true,
  "ticket": "0123456789abcdef0123456789abcdef"
}

Completed batch result

Without a station, or when retrieving a completed station result, the top level is {notes:NoteResult[],folders:FolderResult[]}. HTTP 200 can contain per-item failures. Process every item; never treat response.ok alone as a full-batch save.

Successful note and folder results

HTTP 200
Content-Type: application/json

{
  "notes": [
    {
      "id": "doc-example",
      "ok": true,
      "document": {
        "id": "doc-example",
        "title": "Research notes",
        "folderId": "note-folder-example",
        "content": {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "My observations about the source file."
                }
              ]
            }
          ]
        },
        "createdAt": 1793000000000,
        "updatedAt": 1793000001000,
        "trashedAt": null,
        "driveRevision": "opaque-revision-a",
        "driveFileId": "drive-note-example"
      }
    },
    {
      "id": "doc-remove-example",
      "ok": true,
      "deleted": true
    }
  ],
  "folders": [
    {
      "key": "folder-op:000000000001",
      "id": "note-folder-example",
      "kind": "create",
      "ok": true
    }
  ]
}

Per-item conflict inside an HTTP 200 result

HTTP 200
Content-Type: application/json

{
  "notes": [
    {
      "id": "doc-example",
      "ok": false,
      "status": 409,
      "error": "A conflicting version was preserved.",
      "document": {
        "id": "doc-example",
        "title": "Research notes",
        "folderId": "note-folder-example",
        "content": {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "My observations about the source file."
                }
              ]
            }
          ]
        },
        "createdAt": 1793000000000,
        "updatedAt": 1793000001000,
        "trashedAt": null,
        "driveRevision": "opaque-revision-a",
        "driveFileId": "drive-note-example"
      },
      "conflictDocument": {
        "id": "conflict-doc-example",
        "title": "Research notes (conflict)",
        "folderId": "note-folder-example",
        "content": {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "My observations about the source file."
                }
              ]
            }
          ]
        },
        "createdAt": 1793000000000,
        "updatedAt": 1793000001000,
        "trashedAt": null,
        "driveRevision": "opaque-revision-a",
        "driveFileId": "drive-note-example"
      }
    }
  ],
  "folders": []
}

The server does not echo the upsert/delete token in each note result. Capture {id,token} when dispatching and compare that captured token with the current IndexedDB pending token when applying the result. Folder actions use their echoed key. Echoing operation tokens is optional; mandatory normalized error codes and envelopes are defined in section 10. The existing wire has neither. Preserve the captured-dispatch-token comparison rule.

5 · Temporary tickets and replay

Station duplicate identity uses note IDs/tokens and folder keys/kinds, not a content hash. Never reuse a token/key for different content. There is no general durable upload-session service or end-to-end encryption implied by these tickets. Replay rules and account/disconnect behavior are specified in 12 Failure & Recovery.

6 · Note and folder read compatibility

Required rebuild: use the batch contract for Drive changes and local IndexedDB operations when Drive is inactive. Do not enable a hidden server-note fallback to make old routes return success. Removing a source block from a note is an editor update only: it must not call a source-file deletion endpoint.

7 · Global search uses the current browser snapshot

Search notes and folders without a server note archive

POST /search
Content-Type: application/json

{
  "query": "research",
  "chips": [],
  "page": 0,
  "pageSize": 50,
  "documents": [
    {
      "id": "doc-example",
      "title": "Research notes",
      "folderId": "note-folder-example",
      "content": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "My observations about the source file."
              }
            ]
          }
        ]
      },
      "createdAt": 1793000000000,
      "updatedAt": 1793000001000,
      "trashedAt": null,
      "driveRevision": "opaque-revision-a",
      "driveFileId": "drive-note-example"
    }
  ],
  "folders": [
    {
      "id": "note-folder-example",
      "name": "Sources",
      "parentId": "folder-notes"
    }
  ]
}

HTTP 200
Content-Type: application/json

{
  "items": [
    {
      "id": "paper:doc-example",
      "source": "paper",
      "sourceId": "doc-example",
      "type": "paper",
      "title": "Research notes",
      "createdAt": 1793000000000,
      "tags": [],
      "note": "",
      "author": "",
      "transcript": "",
      "transcriptStatus": "idle",
      "playbackSeconds": 0,
      "lastPlayedMs": 0,
      "meta": {
        "siteHost": "",
        "format": "paper",
        "ext": "paper",
        "sizeBytes": 0
      },
      "remotePath": "paper:doc-example",
      "playlisted": false
    }
  ],
  "total": 1
}

The example shows a complete synthetic note result. Queries/chips are strings; page is zero-based, pageSize defaults to 50 and is clamped to 1–200. documents and folders are optional arrays in the old handler, but are required browser inputs for correct search of unsent work. The snapshot exists only during this request. Global search excludes direct files and trash. Folder result sources are note-folder and folder; result IDs carry that prefix. Optional debug:true adds parser details and is not required UI behavior.

Open a note result by its sourceId using the deliberate one-shot note navigation intent. Do not allow a late search response to replace a newer result or reopen a different note. Media search belongs to the file browser, not this endpoint.

8 · Drive picker and resumable file upload

Synthetic picker item

HTTP 200
Content-Type: application/json

{
  "configured": true,
  "connected": true,
  "email": "example@example.test",
  "folders": [],
  "items": [
    {
      "id": "drive-source-example",
      "name": "Source.pdf",
      "type": "book",
      "size": 1073741824,
      "mtime": 1793000000000,
      "thumbUrl": "",
      "downloadUrl": "/google-drive/raw/drive-source-example",
      "url": "/google-drive/raw/drive-source-example",
      "route": "gdrive:drive-source-example",
      "source": "gdrive",
      "folderId": "drive-parent-example"
    }
  ],
  "breadcrumb": [
    {
      "id": "root",
      "name": "Google Drive"
    }
  ],
  "nextPageToken": ""
}

A generic non-media item uses type:"file" and its url can be a Google Drive view link. Listing folderId is the original remote parent; upload begin’s folderId instead selects local Files library metadata placement. Upload bytes go to the dedicated FileLoveNote Drive upload folder, not a caller-selected remote parent. Do not conflate the two namespaces.

Start a synthetic resumable upload

POST /google-drive/upload/begin
Content-Type: application/json

{
  "name": "Source.pdf",
  "size": 1073741824,
  "type": "application/pdf",
  "folderId": "folder-home"
}

HTTP 200
Content-Type: application/json

{
  "ok": true,
  "uploadId": "0123456789abcdef0123456789abcdef",
  "chunkSize": 8388608,
  "received": 0
}

Upload sessions are bound to the creating login session ID and kept only in process memory. Reload can resume while the same session/process survives; server restart, expired bookkeeping or session rotation can yield 404. Completed records are retained about one hour; abandoned sessions are swept after 24 idle hours when cleanup runs. Current runtime does not guarantee cross-restart resumability. Name claims prevent two concurrent uploads from silently overwriting the same filename. Required rebuild: state recovery limits honestly; if durable resumability is chosen, persist only technical upload metadata, never duplicate GB-sized media or editor notes.

9 · Media, annotations and canvas

Canvas handlers currently depend on resolving the note through the server document service. Browser-only notes have no durable server note record. Required rebuild: define how an authorized browser-only canvas request proves its owning note or keep canvas local until Drive is active; do not restore server note content as a shortcut.

Save an empty synthetic canvas

PUT /api/notes/doc-example/canvas/canvas-example
Content-Type: application/json

{
  "canvas": {
    "format": "notesandfiles-canvas-v1",
    "id": "canvas-example",
    "docId": "doc-example",
    "title": "Source map",
    "createdAt": 1793000000000,
    "updatedAt": 1793000001000,
    "elements": [],
    "connectors": []
  }
}

HTTP 200
Content-Type: application/json

{
  "canvas": {
    "format": "notesandfiles-canvas-v1",
    "id": "canvas-example",
    "docId": "doc-example",
    "title": "Source map",
    "createdAt": 1793000000000,
    "updatedAt": 1793000002000,
    "elements": [],
    "connectors": []
  },
  "summary": {
    "title": "Source map",
    "elementCount": 0,
    "refTitles": []
  }
}

10 · Errors and retry decisions

Existing errors use strings and redirects, not a universal structured envelope. Required new-build contract: all JSON endpoint failures return {error:{code:string,message:string,retryable:boolean},requestId?:string,maxBytes?:number}. requestId is an optional opaque correlation ID, never an account credential; do not log submitted content under it. HTTP 413 requires maxBytes. Batch item failures retain their existing id or key/id/kind correlation and ok:false, add numeric status, and use the same structured error; their 413 failures also include maxBytes. Successful item shapes stay as documented above. Implement a compatibility adapter only if calling the old server; old 302/string examples are not desired new-build responses. retryable:true means the same idempotent request may be retried after the documented delay; false requires a user action or request correction.

Validate against api-error.schema.json and apply Failure & Recovery. Acceptance criteria belong in 15 Acceptance.

11 · Rebuild contract checklist

1. Validate the synthetic examples in fixtures/api-examples.json and round-trip record fixtures from fixtures/records.json; generated schemas must retain the documented optional/null distinctions.
2. Use request-scoped account identity for every route; test two accounts and session rotation. Never make a userKey header an authorization credential.
3. Commit local document and pending operation atomically. Match responses against the captured dispatch token/key, preserve newer edits, and test one lost push response plus one consumed-ticket response.
4. Test full revision pagination, unreadable stubs, missing list entries, deletion tombstones, folder dependency failures and a mixed-success batch.
5. Test upload offset conflict, duplicate finish, two same-name files, process restart and session change. Report which resume boundary is supported.
6. Verify original-source preservation for removing a reference, disconnect, reset and account deletion. Keep explicit note/Drive-Markdown deletion separate from media reference removal.
7. Preserve supported blocks according to 13 Markdown Compatibility; malformed metadata must not blank a good note.
8. Record actual contract test evidence and live OAuth/Drive evidence separately using 14 Setup & Operations and 15 Acceptance. These examples are specifications, not executed live tests.