docs: update integration API documentation for read-note endpoint

Add read-note endpoint to README API table, update endpoint count,
and revise security tradeoff text to cover both create and read operations.

Author: SaschaWebDev

README.md

@@ -309,7 +309,7 @@ worker/
 
 ## 📡 API
 
-Six endpoints. That's the entire backend.
+Eight endpoints. That's the entire backend.
 
 | Method   | Endpoint          | Description                      |
 | -------- | ----------------- | -------------------------------- |
@@ -324,15 +324,16 @@ Rate limited per IP. Max request body: 1 KB. Full API docs at [notefade.com/docs
 
 ### ⚠️ Third-Party Integration API
 
-> **Security tradeoff:** This endpoint does NOT follow the zero-knowledge model. The server briefly sees plaintext (~1-2ms in volatile Worker memory) before encrypting. Never stored, never logged — but the server processes content, which the main application never does. Use the main app for sensitive secrets.
+> **Security tradeoff:** These endpoints do NOT follow the zero-knowledge model. The server briefly sees plaintext (~1-2ms in volatile Worker memory) during encryption or decryption. Never stored, never logged — but the server processes content, which the main application never does. The read endpoint additionally requires the full note URL (including the `#` fragment) to be sent to the server. Use the main app for sensitive secrets.
 
-| Method | Endpoint              | Description                            |
-| ------ | --------------------- | -------------------------------------- |
-| `POST` | `/api/v1/create-note` | Create a note (server-side encryption) |
+| Method | Endpoint              | Description                             |
+| ------ | --------------------- | --------------------------------------- |
+| `POST` | `/api/v1/create-note` | Create a note (server-side encryption)  |
+| `POST` | `/api/v1/read-note`   | Read a note (server-side decryption)    |
 
-Requires an `X-Api-Key` header. Rate limited per key (60 req/min, KV-based). Max body: 4 KB. Fixed 24-hour TTL.
+Requires an `X-Api-Key` header. Rate limited per key (60 req/min, KV-based). Max body: 4 KB (create) / 16 KB (read). Fixed 24-hour TTL for created notes.
 
-This is a convenience endpoint for trusted third-party apps that need to create notes programmatically. It produces the same encrypted output as the main app — AES-256-GCM, XOR key splitting, one-time-read — but encryption happens on the server instead of in the browser. See [notefade.com/docs#integration-api](https://notefade.com/docs#integration-api) for full documentation and security details.
+These are convenience endpoints for trusted third-party apps that need to create or read notes programmatically. They produce and consume the same encrypted format as the main app — AES-256-GCM, XOR key splitting, one-time-read — but crypto operations happen on the server instead of in the browser. See [notefade.com/docs#integration-api](https://notefade.com/docs#integration-api) for full documentation and security details.
 
 ## 📄 License
 

src/components/docs/IntegrationApi.tsx

@@ -8,22 +8,27 @@ export function IntegrationApi() {
   return (
     <DocsSection id='integration-api' title='integration API (third-party)'>
       <DocsCallout variant='danger'>
-        This endpoint does <strong>not</strong> follow notefade's zero-knowledge
-        security model. The server receives plaintext, encrypts it, and returns
-        a note URL. Plaintext is held in volatile Worker memory for ~1-2ms —
-        never stored, never logged, no filesystem — but the server{' '}
-        <em>processes</em> content, which the main application never does. Do
-        not send highly sensitive plaintext through this endpoint ONLY EVER SEND
-        ALREADY ENCRYPTED TEXT. It is a convenience API for trusted third-party
+        These endpoints do <strong>not</strong> follow notefade's zero-knowledge
+        security model. The create endpoint receives plaintext and encrypts it
+        on the server. The read endpoint fetches the shard, reconstructs the
+        key, and decrypts on the server. In both cases, plaintext is held in
+        volatile Worker memory for ~1-2ms — never stored, never logged, no
+        filesystem — but the server <em>processes</em> content, which the main
+        application never does. Do not send highly sensitive plaintext through
+        the create endpoint — ONLY EVER SEND ALREADY ENCRYPTED TEXT. The read
+        endpoint will return whatever the note contains, so if the content was
+        pre-encrypted before creation, the server only ever sees the opaque
+        ciphertext. These are convenience APIs for trusted third-party
         applications, not a replacement for the main application's client-side
         encryption.
       </DocsCallout>
 
       <p className={styles.text}>
-        The integration API lets third-party applications create encrypted notes
-        with a single HTTP request. It produces the same encrypted output as the
-        main app — AES-256-GCM, XOR key splitting, one-time-read — but
-        encryption happens on the server instead of in the browser.
+        The integration API lets third-party applications create and read
+        encrypted notes with a single HTTP request. It uses the same
+        AES-256-GCM encryption and XOR key splitting as the main app, but
+        encryption and decryption happen on the server instead of in the
+        browser.
       </p>
 
       <h3 className={styles.subheading}>How it differs from the main app</h3>
@@ -41,6 +46,11 @@ export function IntegrationApi() {
             <td>Client (browser)</td>
             <td>Server (Worker isolate)</td>
           </tr>
+          <tr>
+            <td>Decryption location</td>
+            <td>Client (browser)</td>
+            <td>Server (Worker isolate)</td>
+          </tr>
           <tr>
             <td>Server sees plaintext</td>
             <td>Never</td>
@@ -66,13 +76,17 @@ export function IntegrationApi() {
 
       <h3 className={styles.subheading}>When to use this</h3>
       <ul className={styles.list}>
-        <li>Third-party apps that need to create notes programmatically</li>
+        <li>Third-party apps that need to create or read notes programmatically</li>
         <li>
           Server-side services where importing the crypto module isn't practical
         </li>
         <li>
           Trusted integrations owned by the same operator running the Worker
         </li>
+        <li>
+          Consuming notes that were created with pre-encrypted content — the
+          server only sees the opaque ciphertext, not the underlying secret
+        </li>
       </ul>
 
       <h3 className={styles.subheading}>When NOT to use this</h3>
@@ -144,7 +158,12 @@ export function IntegrationApi() {
       <ul className={styles.list}>
         <li>
           Plaintext is visible to the Worker isolate for ~1-2ms during
-          encryption
+          encryption or decryption
+        </li>
+        <li>
+          The read endpoint requires sending the full note URL (including
+          fragment) to the server — in normal browser usage, the fragment never
+          leaves the client
         </li>
         <li>
           Cloudflare (as the infrastructure provider) could theoretically

src/components/docs/docs-data.ts

@@ -370,6 +370,52 @@ X-RateLimit-Reset: 1710720060
   "url": "https://notefade.com/#a1b2c3d4e5f67890:...",
   "shardId": "a1b2c3d4e5f67890",
   "expiresAt": 1710806400000
+}`,
+  },
+  {
+    method: 'POST',
+    path: '/api/v1/read-note',
+    summary: 'Read a note (server-side decryption)',
+    description:
+      'Accepts a note URL, fetches the shard from storage, reconstructs the encryption key, and decrypts the content on the server. The shard is consumed — the note cannot be read again. Plaintext is held in volatile Worker memory for ~1-2ms during decryption — never stored, never logged. The full note URL (including fragment) must be sent to the server, which means the server momentarily has access to all key material. Requires a valid API key via the X-Api-Key header. Multi-chunk and custom-provider notes are not supported.',
+    params: [
+      {
+        name: 'url',
+        location: 'body',
+        type: 'string',
+        required: true,
+        description: 'The full note URL including the fragment (e.g. https://notefade.com/#shardId:check:payload). The fragment is required — it contains the encrypted data and key material.',
+        pattern: 'Must contain # fragment',
+      },
+    ],
+    responses: [
+      {
+        status: 200,
+        description: 'Note decrypted and returned',
+        body: '{ "text": "The secret message content", "shardId": "a1b2c3d4e5f67890" }',
+      },
+      { status: 400, description: 'Invalid URL, bad fragment format, integrity check failed, or multi-chunk/custom-provider URL' },
+      { status: 401, description: 'Missing or invalid API key' },
+      { status: 404, description: 'Note not found — already read, expired, or invalid shard ID' },
+      { status: 413, description: 'Request body exceeds 16 KB' },
+      { status: 429, description: 'Per-key rate limit exceeded' },
+    ],
+    exampleRequest: `POST /api/v1/read-note HTTP/1.1
+Content-Type: application/json
+X-Api-Key: nfk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
+
+{
+  "url": "https://notefade.com/#a1b2c3d4e5f67890:aBcDeF:..."
+}`,
+    exampleResponse: `HTTP/1.1 200 OK
+Content-Type: application/json
+X-RateLimit-Limit: 60
+X-RateLimit-Remaining: 59
+X-RateLimit-Reset: 1710720060
+
+{
+  "text": "The deploy credentials are ...",
+  "shardId": "a1b2c3d4e5f67890"
 }`,
   },
 ]