Quickstart Guide

Step 1 — Create an account

Register with your email and password. A verification email will be sent automatically.

curl -X POST https://textwatermarking.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "yourpassword"}'

# Response: { "message": "Registration successful. Please check your email." }

Click the verification link in your inbox, then log in:

curl -X POST https://textwatermarking.com/api/auth/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email": "[email protected]", "password": "yourpassword"}'

# Response:
# {
#   "accessToken": "eyJhbGci...",   ← save this, valid for 2 hours
#   "user": { "id": "...", "plan": "free", ... }
# }

Step 2 — Create an API token

Watermark calls use a long-lived API token (not your login JWT). Create one from the dashboard, or via API:

curl -X POST https://textwatermarking.com/api/v2/tokens \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{"name": "My first token", "permissions": ["encode", "decode"]}'

# Response:
# {
#   "token": "a3f8e2b1c9d47f6a...",   ← shown ONCE — store it now
#   "id": "...",
#   "name": "My first token",
#   "token_prefix": "mcp_a3f8e2b1"
# }

# Save to your environment
export TWM_TOKEN="a3f8e2b1c9d47f6a..."

Step 3 — Encode your first watermark

Embed a secret string invisibly into carrier text using Unicode variation selectors. The output looks identical to the original.

curl -X POST https://textwatermarking.com/api/watermark/encode \
  -H "Authorization: Bearer $TWM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The quick brown fox jumps over the lazy dog",
    "secret": "owner-id:user_42"
  }'

Response (200 OK):

{
  "encoded": "The quick brown fox jumps over the lazy dog",
  "keyed": false,
  "stats": {
    "originalLength": 43,
    "secretLength": 17,
    "encodedLength": 60,
    "chunkSize": 1,
    "method": "auto"
  }
}

The encoded value looks identical to the input but carries hidden bytes. Copy and paste it as-is — the watermark travels with the text. Each call deducts 1 credit; the response includes an X-Credits-Remaining header.

Step 4 — Decode the watermark

Pass the watermarked text back to recover the hidden secret.

curl -X POST https://textwatermarking.com/api/watermark/decode \
  -H "Authorization: Bearer $TWM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "<paste the encoded value here>"}'

Response (200 OK):

{
  "decoded": "owner-id:user_42",
  "keyed": false
}

If the text has been stripped of invisible characters, decoded will be null or an empty string.

Step 5 — What's next