API Overview

The TextWatermark API lets you embed invisible watermarks inside text and extract them later — even after copying, reformatting, or minor edits. Use it to trace document leaks, verify authorship, or track AI-generated content.

Base URL

https://textwatermarking.com

All endpoints are HTTPS. There is no separate API subdomain — the app and API share the same host.

Versioning

The current API version is v2. Account management endpoints are prefixed /api/v2/. Watermarking endpoints use /api/watermark/ (unversioned — stable).

Prefix Covers
/api/auth/ Register, login, email verification, token refresh, logout
/api/v2/users/ Account profile, password change
/api/v2/tokens/ API token management (create, list, revoke)
/api/v2/channels/ Signing channel management
/api/watermark/ Encode and decode watermarks (API-token authenticated)
/api/v2/credits/ Credit balance and usage history

Authentication

The API uses two separate credential types depending on what you're doing:

Credential Format Used for
JWT access token Authorization: Bearer <jwt> Account endpoints — profile, tokens, channels, credits
API token Authorization: Bearer Watermarking — encode & decode (server-to-server)

JWTs expire after 2 hours and are refreshed via a httpOnly refresh cookie (30-day TTL). API tokens do not expire — revoke them from your dashboard when no longer needed. See Authentication for full details.

Core Concepts

Zero-width watermarking. We embed data using Unicode zero-width characters inserted between visible characters. The resulting text looks and renders identically to the original — no visual change, no layout shift.

Secret (payload). The string you want to hide inside the text. Passed as the secret field on encode. Recovered as decoded on decode.

Signing channels. Named channel objects that pair a channel name with a signing key. When a watermarked request references a channel, the server verifies the watermark signature — proving it was produced by your key, not forged.

Resilience. The standard mode uses fast zero-width insertion. Robust mode adds redundant encoding that survives moderate text editing, copy-paste, or format conversion. Choose based on your threat model.

Credits. Each watermark operation consumes credits from your balance. Subscription plans include a monthly credit allocation; additional credits can be purchased. Credits never expire while your account is active.

System Flow

TextWatermark System Flow Diagram

Text enters the encoder with a secret; zero-width characters are inserted to carry the encoded payload. On decode, the characters are extracted and the original secret is recovered.

Response Format

All responses are application/json. Errors follow a consistent shape:

{
  "error": "Unauthorized",
  "message": "Invalid or missing token"
}

See Error Handling for the full list of status codes and messages.

Rate Limits

Watermark operations are metered by credits, not by request rate. Account management endpoints (login, register, etc.) have per-IP throttling to prevent abuse. When a limit is hit, the API returns 429 Too Many Requests with a Retry-After header.

Next Steps