My paraphraser

Your text

setText(event.target.value)} required style={{display:'block',width:'100%',height:180,padding:12}}/><button disabled={busy||!text.trim()}>{busy?'Writing…':'Paraphrase'}</button></form>{error&&<p role="alert">{error}</p>}<h2>Result</h2><pre style={{whiteSpace:'pre-wrap'}} aria-live="polite">{output}</pre></main>;
}
```

Run `npm run dev` and open the local URL. The conservative 30/minute demo limiter is shared by users in one process. For a public multi-instance application, use your app's authentication and a Redis-backed limiter. The MetaPhrase secret stays in the route handler; the React component receives only the response.

For an existing React/Vite app, use the same page component and [the standalone Node proxy](https://metaphrase.msalman.com/docs/recipe-html.md). Configure your dev server to forward `/api/metaphrase` to that backend. Do not move the secret into a Vite environment variable.

---

# WordPress plugin recipe

Add a paraphraser shortcode whose requests go through WordPress, never through a browser secret key.

Configure `METAPHRASE_API_KEY` as a private server environment variable. In `wp-config.php`, before the final stop-editing comment, add:

```php
define('METAPHRASE_API_KEY', getenv('METAPHRASE_API_KEY') ?: '');
```

Create `wp-content/plugins/metaphrase-writing/metaphrase-writing.php` with this complete plugin, activate it, and insert `[metaphrase_writer]` into a page:

```php
<?php
/**
 * Plugin Name: MetaPhrase Writing
 * Description: A backend-proxied writing form with a public shortcode.
 * Version: 1.0.0
 */
if (!defined('ABSPATH')) { exit; }
add_shortcode('metaphrase_writer', function () {
    $id = wp_unique_id('metaphrase-');
    $ajax = admin_url('admin-ajax.php');
    $nonce = wp_create_nonce('metaphrase_write');
    ob_start(); ?>
    <div id="<?php echo esc_attr($id); ?>">
      <form><label>Your text<textarea name="text" required style="display:block;width:100%;min-height:160px">

'Refresh the page and retry.'],403); } $ip = $_SERVER['REMOTE_ADDR'] ?? 'unknown'; $limit_key = 'mp_ip_' . hash_hmac('sha256',$ip,wp_salt('nonce')); $count = (int) get_transient($limit_key); if ($count >= 15) { header('Retry-After: 60'); wp_send_json_error(['message'=>'Please wait a minute.'],429); } set_transient($limit_key,$count+1,60); if (!defined('METAPHRASE_API_KEY') || !METAPHRASE_API_KEY) { wp_send_json_error(['message'=>'The server API key is not configured.'],503); } $text = isset($_POST['text']) && is_string($_POST['text']) ? sanitize_textarea_field(wp_unslash($_POST['text'])) : ''; if (!$text || strlen($text) > 80000 || preg_match_all('/./us',$text) > 20000) { wp_send_json_error(['message'=>'Enter text within the character limit.'],400); } $response = wp_remote_post('https://metaphrase.msalman.com/api/v1/paraphrase',[ 'timeout'=>250, 'headers'=>['Authorization'=>'Bearer '.METAPHRASE_API_KEY,'Content-Type'=>'application/json'], 'body'=>wp_json_encode(['text'=>$text,'mode'=>'standard','stream'=>false]), ]); if (is_wp_error($response)) { wp_send_json_error(['message'=>'The writing service could not be reached.'],502); } $status = wp_remote_retrieve_response_code($response); $value = json_decode(wp_remote_retrieve_body($response),true); if ($status >= 400) { wp_send_json_error(['message'=>$value['error']['message']??'Please retry.','docs_url'=>$value['error']['docs_url']??''], $status); } wp_send_json_success(['text'=>$value['result']['text']]); } add_action('wp_ajax_metaphrase_write','metaphrase_write_handler'); add_action('wp_ajax_nopriv_metaphrase_write','metaphrase_write_handler'); ``` The nonce protects the browser action; the IP throttle is a conservative demo guard. WordPress transients are not an atomic distributed limiter. For high traffic use your site's authenticated access or an atomic shared limiter, and configure WordPress's trusted reverse proxy handling so client IPs cannot be spoofed. If the site uses a strict CSP, move the inline handler into an enqueued script with your site's nonce policy. For a simpler public box with no WordPress backend integration, use [the widget script](https://metaphrase.msalman.com/docs/widget.md). --- # Laravel integration Use Laravel's HTTP client from a server controller and keep the key in configuration. In a fresh Laravel application set `METAPHRASE_API_KEY` in private `.env`. Add this entry to the array returned by `config/services.php`, preserving your other service settings: ```php 'metaphrase' => [ 'key' => env('METAPHRASE_API_KEY'), 'base_url' => env('METAPHRASE_BASE_URL', 'https://metaphrase.msalman.com'), ], ``` Save as `app/Http/Controllers/MetaPhraseController.php`: ```php validate(['text'=>['required','string','max:20000']]); $key = config('services.metaphrase.key'); if (!$key) return response()->json(['error'=>['message'=>'The backend key is not configured.']],503); try { $result = Http::withToken($key)->acceptJson()->timeout(250) ->post(rtrim(config('services.metaphrase.base_url'),'/').'/api/v1/paraphrase',[ 'text'=>$data['text'],'mode'=>'standard','stream'=>false, ]); return response()->json($result->json(),$result->status()) ->header('Cache-Control','no-store'); } catch (\Illuminate\Http\Client\ConnectionException $error) { return response()->json(['error'=>['message'=>'The writing service could not be reached.']],502); } } } ``` For a fresh example, `routes/web.php` can contain: ```php middleware('throttle:15,1'); ``` Save as `resources/views/writer.blade.php`: ```html My paraphraser

My paraphraser

``` Run `php artisan config:clear` after changing local configuration, then `php artisan serve`. Laravel's web CSRF middleware and throttle remain enabled. For production configure your application's authentication, trusted proxies and shared throttle store as usual. The browser receives no API key. The Blade `{{ csrf_token() }}` expression is Laravel syntax and must remain unchanged. --- # Django and FastAPI backends Call MetaPhrase from a Python server and expose only your own proxy route to the browser. Set `METAPHRASE_API_KEY` in the backend environment. Both examples use Python's standard-library HTTP client for the MetaPhrase call, preserve error JSON, and never render the key. Use the [plain HTML page](https://metaphrase.msalman.com/docs/recipe-html.md) as `index.html`; it already posts to `/api/metaphrase` without a key. ## FastAPI Create a virtual environment, install the framework, and save the complete server below as `app.py` alongside `index.html`. ```bash python3 -m venv .venv . .venv/bin/activate python -m pip install fastapi uvicorn uvicorn app:app --host 127.0.0.1 --port 4000 ``` ```python import asyncio import json import os import threading import time from pathlib import Path from urllib.request import Request, urlopen from urllib.error import HTTPError, URLError from fastapi import FastAPI, Request as WebRequest from fastapi.responses import FileResponse, JSONResponse app = FastAPI() api_key = os.environ['METAPHRASE_API_KEY'] api_origin = os.environ.get('METAPHRASE_BASE_URL', 'https://metaphrase.msalman.com').rstrip('/') public_origin = os.environ.get('PUBLIC_ORIGIN', 'http://127.0.0.1:4000') lock = threading.Lock() window = {'start': 0.0, 'count': 0} def upstream(text): request = Request(api_origin + '/api/v1/paraphrase', data=json.dumps({'text': text, 'mode': 'standard', 'stream': False}).encode(), headers={'Authorization': 'Bearer ' + api_key, 'Content-Type': 'application/json'}, method='POST') try: with urlopen(request, timeout=250) as response: return response.status, json.load(response) except HTTPError as error: return error.code, json.loads(error.read()) except (URLError, TimeoutError): return 502, {'error': {'message': 'The writing service could not be reached.'}} @app.get('/') def index(): return FileResponse(Path(__file__).with_name('index.html')) @app.post('/api/metaphrase') async def paraphrase(request: WebRequest): if request.headers.get('origin') not in (None, public_origin): return JSONResponse({'error': {'message': 'Origin not allowed'}}, status_code=403) with lock: now = time.monotonic() if now - window['start'] >= 60: window.update(start=now, count=0) window['count'] += 1 if window['count'] > 30: return JSONResponse({'error': {'message': 'Please wait a minute.'}}, status_code=429, headers={'Retry-After':'60'}) raw = bytearray() async for chunk in request.stream(): raw.extend(chunk) if len(raw) > 120000: return JSONResponse({'error': {'message': 'Request too large'}}, status_code=413) try: value = json.loads(raw) text = value.get('text') if isinstance(value, dict) else None if not isinstance(text, str) or not text.strip() or len(text) > 20000: raise ValueError() except (ValueError, UnicodeError): return JSONResponse({'error': {'message': 'Enter valid text within the character limit.'}}, status_code=400) status, result = await asyncio.to_thread(upstream, text) return JSONResponse(result, status_code=status, headers={'Cache-Control':'no-store'}) ``` Open `http://127.0.0.1:4000`. The demo guard is a shared 30/minute process limit. Use your production application's authentication and a shared limiter when scaling to multiple workers. ## Django For a fresh project: ```bash python -m pip install Django mkdir django-writer cd django-writer django-admin startproject writer . ``` Copy `index.html` from the HTML recipe beside `manage.py`. In that HTML page's fetch headers add `'X-CSRFToken': document.cookie.split('; ').find(item=>item.startsWith('csrftoken='))?.split('=')[1] ?? ''`. Django issues this cookie on the initial GET below. Do not disable CSRF middleware. Save `writer/views.py`: ```python import json import os from pathlib import Path from urllib.request import Request, urlopen from urllib.error import HTTPError, URLError from django.core.cache import cache from django.http import HttpResponse, JsonResponse from django.views.decorators.csrf import ensure_csrf_cookie from django.views.decorators.http import require_POST @ensure_csrf_cookie def index(request): return HttpResponse((Path(__file__).resolve().parent.parent / 'index.html').read_text(), content_type='text/html') @require_POST def paraphrase(request): cache.add('metaphrase_demo_window', 0, 60) if cache.incr('metaphrase_demo_window') > 30: response = JsonResponse({'error': {'message': 'Please wait a minute.'}}, status=429) response['Retry-After'] = '60' return response if int(request.META.get('CONTENT_LENGTH') or 0) > 120000 or len(request.body) > 120000: return JsonResponse({'error': {'message': 'Request too large'}}, status=413) try: value = json.loads(request.body) text = value.get('text') if isinstance(value, dict) else None if not isinstance(text, str) or not text.strip() or len(text) > 20000: raise ValueError() except (ValueError, UnicodeError): return JsonResponse({'error': {'message': 'Enter valid text within the character limit.'}}, status=400) key = os.environ.get('METAPHRASE_API_KEY') if not key: return JsonResponse({'error': {'message': 'Backend key is not configured.'}}, status=503) base = os.environ.get('METAPHRASE_BASE_URL', 'https://metaphrase.msalman.com').rstrip('/') upstream = Request(base + '/api/v1/paraphrase', data=json.dumps({'text':text,'mode':'standard','stream':False}).encode(), headers={'Authorization':'Bearer '+key,'Content-Type':'application/json'}, method='POST') try: with urlopen(upstream, timeout=250) as response: result, status = json.load(response), response.status except HTTPError as error: result, status = json.loads(error.read()), error.code except (URLError, TimeoutError): result, status = {'error': {'message': 'The writing service could not be reached.'}}, 502 response = JsonResponse(result, status=status) response['Cache-Control'] = 'no-store' return response ``` Save `writer/urls.py`: ```python from django.urls import path from . import views urlpatterns = [path('', views.index), path('api/metaphrase', views.paraphrase)] ``` Run `python manage.py migrate`, then `python manage.py runserver 127.0.0.1:4000`. Use your application's authentication and shared cache/rate controls for public production access. Both examples keep the MetaPhrase secret strictly in the Python process. --- # Android, iOS and Flutter via a backend Mobile apps call your own backend proxy, never the MetaPhrase secret-key endpoint directly. First deploy [the HTML/Node proxy](https://metaphrase.msalman.com/docs/recipe-html.md), [Next.js proxy](https://metaphrase.msalman.com/docs/recipe-nextjs.md), or [Python proxy](https://metaphrase.msalman.com/docs/recipe-python.md) at your own HTTPS origin. Its `POST /api/metaphrase` accepts `{"text":"..."}` and returns the full MetaPhrase response. Replace the example `https://your-app.example/api/metaphrase` with that actual URL. The backend alone stores `METAPHRASE_API_KEY`. Apply your app's normal login/session protection to this proxy. ## iOS (SwiftUI) Create a SwiftUI iOS application in Xcode and replace its app source with this complete file. Set `proxyURL` to your backend URL. No MetaPhrase key is included in the app. ```swift import SwiftUI struct WritingResponse: Decodable { struct Result: Decodable { let text: String } struct Failure: Decodable { let message: String } let result: Result? let error: Failure? } @main struct WriterApp: App { var body: some Scene { WindowGroup { WriterView() } } } struct WriterView: View { @State private var text = "" @State private var output = "" @State private var error = "" @State private var busy = false private let proxyURL = URL(string: "https://your-app.example/api/metaphrase")! var body: some View { NavigationStack { VStack(alignment: .leading, spacing: 16) { Text("Your text").font(.headline) TextEditor(text: $text).frame(minHeight: 150).border(.secondary) Button(busy ? "Writing…" : "Paraphrase") { Task { await paraphrase() } } .disabled(busy || text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty) if !error.isEmpty { Text(error).foregroundStyle(.red).accessibilityLabel("Error: \(error)") } ScrollView { Text(output).frame(maxWidth: .infinity, alignment: .leading).textSelection(.enabled) } }.padding().navigationTitle("My paraphraser") } } @MainActor private func paraphrase() async { busy = true; error = "" defer { busy = false } do { var request = URLRequest(url: proxyURL) request.httpMethod = "POST" request.timeoutInterval = 250 request.setValue("application/json", forHTTPHeaderField: "Content-Type") request.httpBody = try JSONEncoder().encode(["text": text]) let (data, response) = try await URLSession.shared.data(for: request) let value = try JSONDecoder().decode(WritingResponse.self, from: data) guard let http = response as? HTTPURLResponse, (200..<300).contains(http.statusCode), let result = value.result else { error = value.error?.message ?? "Please try again." return } output = result.text } catch { self.error = error.localizedDescription } } } ``` ## Android / iOS (Flutter) Run `flutter create my_writer`, then `cd my_writer` and `flutter pub add http`. Replace `lib/main.dart` with this complete app. Launch with `flutter run --dart-define=BACKEND_URL=https://your-app.example/api/metaphrase`. ```dart import 'dart:convert'; import 'package:flutter/material.dart'; import 'package:http/http.dart' as http; void main() => runApp(const MaterialApp(home: WriterPage())); class WriterPage extends StatefulWidget { const WriterPage({super.key}); @override State createState() => _WriterPageState(); } class _WriterPageState extends State { final input = TextEditingController(); String output = '', error = ''; bool busy = false; static const backend = String.fromEnvironment('BACKEND_URL'); @override void dispose() { input.dispose(); super.dispose(); } Future paraphrase() async { setState(() { busy = true; error = ''; }); try { if (backend.isEmpty) throw StateError('Set BACKEND_URL to your backend proxy'); final response = await http.post(Uri.parse(backend), headers:{'Content-Type':'application/json'}, body:jsonEncode({'text':input.text})).timeout(const Duration(seconds:250)); final value = jsonDecode(response.body) as Map; if (response.statusCode >= 400) throw Exception(value['error']?['message'] ?? 'Please retry.'); if (mounted) setState(() { output = value['result']['text'] as String; }); } catch (failure) { if (mounted) setState(() { error = failure.toString(); }); } finally { if (mounted) setState(() { busy = false; }); } } @override Widget build(BuildContext context) => Scaffold( appBar:AppBar(title:const Text('My paraphraser')), body:Padding(padding:const EdgeInsets.all(20), child:ListView(children:[ TextField(controller:input,maxLines:7,decoration:const InputDecoration(labelText:'Your text',border:OutlineInputBorder())), const SizedBox(height:16), FilledButton(onPressed:busy ? null : paraphrase, child:Text(busy ? 'Writing…' : 'Paraphrase')), if(error.isNotEmpty) Semantics(liveRegion:true,child:Text(error,style:TextStyle(color:Theme.of(context).colorScheme.error))), const SizedBox(height:20),SelectableText(output), ])), ); } ``` Keep Android's INTERNET permission enabled in the release manifest (`` inside ``, outside ``). Use HTTPS so iOS App Transport Security and Android cleartext restrictions need no exceptions. `BACKEND_URL` is public app configuration, not a secret key. Never replace it with a MetaPhrase API key. --- # Lovable, Bolt, Zapier and Make Use server actions or a backend webhook step so your secret key never enters a public page. ## Lovable, Bolt and AI app builders Add `METAPHRASE_API_KEY` to the platform's **server secrets** or backend/edge-function environment. Do not use a frontend/Vite/public variable. Ask the assistant: > Integrate the MetaPhrase paraphrase API into my app. Read https://metaphrase.msalman.com/llms-full.txt first. The secret is in server env var METAPHRASE_API_KEY. Create a server/edge proxy that accepts text, calls POST https://metaphrase.msalman.com/api/v1/paraphrase with Authorization: Bearer from that environment variable and application/json, and returns the full JSON envelope. The frontend calls only my proxy and reads result.text. Validate text length, use my app's login and rate controls, handle error.code/message/docs_url and Retry-After, and never expose or log the secret. Do not invent request fields. The expected upstream body is: ```json {"text":"Good writing helps people understand an idea.","mode":"standard","synonym_strength":50,"stream":false} ``` The server reads the API key from its secret store. The frontend displays `response.result.text`; it must not assume the response is just a string. The [Next.js](https://metaphrase.msalman.com/docs/recipe-nextjs.md) and [plain HTML proxy](https://metaphrase.msalman.com/docs/recipe-html.md) show working implementations you can adapt to the platform's backend. ## Zapier 1. Choose your trigger, for example a form submission or **Webhooks by Zapier → Catch Hook**. Treat the incoming hook URL as a private workflow capability. 2. Add **Webhooks by Zapier → Custom Request** with method POST and URL `https://metaphrase.msalman.com/api/v1/paraphrase`. 3. Set `Content-Type` to `application/json` and `Authorization` to `Bearer ` followed by your key from a private connection/secret field. Keep it out of public form fields. 4. Send the JSON body above, mapping the trigger's text into `text`. Keep `stream:false`; ordinary workflow HTTP steps expect one JSON response. 5. Map the output `result.text` into the next action. Store `request_id` if you need support or traceability. 6. On 429 honor `Retry-After`; on `quota_exceeded` stop or delay until reset rather than looping. See [reliability](https://metaphrase.msalman.com/docs/reliability.md). ## Make Use **Webhooks → Custom webhook** (or your existing trigger), then **HTTP → Make a request**. Select POST, use the same endpoint/headers, body type Raw with content type JSON, and enable response parsing. Map the input text into a JSON-escaped string, then read the parsed `result.text`. Store the Bearer key in a private connection/secret, not an input variable that the browser sends. Configure an error handler for 429/503 with bounded retries and a quota/budget stop condition. These are incoming automation triggers followed by a synchronous API call. MetaPhrase does not send outgoing completion webhooks. A missing-provider 503 requires the MetaPhrase operator's configuration; changing a no-code mapping will not fix it. ## No backend available Use [the embeddable widget](https://metaphrase.msalman.com/docs/widget.md) instead of putting a secret key into a browser-only API connector. The widget script contains only a public widget ID and can be pasted into a custom HTML component. --- # Changelog and versioning REST v1 uses explicit versioned paths and a stable snake_case contract. ## 1.0.0 — initial API contract - Six POST endpoints under `/api/v1`: paraphrase, grammar, detect, translate, summarize and cite. - Bearer keys, per-key rates/UTC monthly quotas, usage accounting and revocation. - SSE for paraphrase rewrites, translation and summarization; consistent JSON errors and exact fix links. - Grammar/citation/extractive summaries with zero LLM token cost. - Public OpenAPI 3.1, Markdown pages, llms.txt/full, language samples, SDK archives, Postman and Insomnia exports. - Origin-restricted paraphraser widget with a public identifier and no frontend secret key. ## Compatibility policy Breaking changes to request/response meaning, removed fields, renamed fields, changed required parameters or incompatible error behavior require a new major REST path such as `/api/v2`. Additive optional fields, new optional parameters, new enum values and improved wording may be released within v1. Clients should tolerate unknown response fields and handle documented errors by `error.code`, not English message text. New enum values should be handled with a fallback in UI code. OpenAPI `info.version` and SDK versions describe the contract release. SDK patch releases can fix client behavior without changing the API version. Keep the OpenAPI checksum with generated artifacts. Provider/model choice is runtime configuration and can change wording or model cost without a new API version; the response always reports the provider/model used. Plans and deployment limits can change; runtime OpenAPI input limits and response rate/quota headers are authoritative. Deprecated endpoints will remain documented with a migration guide and a dated notice before removal. No prior versions or deprecation dates exist yet. This is an early access deployment with Free/Pro placeholders and no payments.

A fresh way to say it

Result

My paraphraser

My paraphraser