API reference

One endpoint turns a name into a signature image. Send JSON with your API key, get the image back in the response body, with its metadata in X-Signature-* headers.

Quickstart

  1. Create a key

    Open the Dashboard and create a key. It is shown once; keep it on your server, never in a browser or a mobile app.

  2. Authenticate

    Send the key with every request as Authorization: Bearer hs_live_… or X-API-Key.

  3. Generate a signature

    POST /v1/signatures returns the image directly in the response body.

    curl https://handsign.app/v1/signatures \
  -H "Authorization: Bearer $HANDSIGN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Camille Laurent",
    "style": "executive",
    "size": "L",
    "pen": "fountain",
    "color": "navy",
    "background": "transparent",
    "format": "png"
  }' \
  -o signature.png

Parameters

JSON body of POST /v1/signatures. Only name is required.

Text

name required

1 to 80 characters. Accents are normalized.

name_format string

Which part of the name is written. Every style writes the full name by default.

fullinitial_lastfirst_initialinitialsfirstlastshort

Handwriting

style default random

Overall look of the signature.

randomclassicexecutiveflowingsharpminimalloopscribble
handwriting 0 to 12

The base handwriting. Random by default.

flourish default auto

Decorative stroke added to the signature.

autononeunderlineswooshstriketailovalinitial_loopzigzagslash
legibility 0 to 1

From 0 (loose) to 1 (neat).

slant -30 to 45

Slant in degrees.

Pen

pen default ballpoint

Pen used to draw the strokes.

ballpointgelfinelinerfountainmarkerpencil
color name or hex

Ink color: a name or #RRGGBB.

blackbluenavyroyalredgreengray
stroke_scale 0.1 to 5

Line width multiplier.

Output

format default png

Image format of the response body.

pngwebpjpegsvg
size default M

Image width: S 128 px, M 256 px, L 512 px or XL 1024 px. Height follows the signature.

SMLXL
scale default 1

Pixel density, like @2x images. "size": "S", "scale": 2 returns 256 real pixels meant to be shown at 128 px on Retina screens. Ignored for SVG.

123
background default transparent

transparent, a color name, #RRGGBB or #RRGGBBAA.

seed 0 to 2147483647

The same seed and parameters always give the same signature.

Response

A successful call returns 200 with the image as the body and its Content-Type set to the requested format. Metadata comes in headers.

Response headers 11
X-Signature-Seed
Seed used, to reproduce the signature
X-Signature-Style
Style used
X-Signature-Text
Text written, after name_format
X-Signature-Size
Size used
X-Signature-Scale
Scale used
X-Signature-Width
Image width in pixels
X-Signature-Height
Image height in pixels
X-Signature-Handwriting
Handwriting used
X-Signature-Flourishes
Flourishes drawn, comma separated
X-Signature-Legible
true when an automatic reader read the written text back correctly
X-Signature-Elapsed-Ms
Generation time in milliseconds

Endpoints

POST /v1/signatures/batch

Same body plus count (1 to 16). Returns JSON with base64 images. Starter plan and above.

GET /v1/styles

Every accepted value, as JSON. No key needed.

GET /v1/plans

Plans and quotas, as JSON. No key needed.

GET /health

Service status.

Errors

Error bodies are JSON shaped as {"detail": "…"}.

401 Unauthorized

Missing, invalid or revoked API key.

403 Forbidden

Not available on your plan (batch), or key limit reached.

422 Invalid parameters

A parameter is missing or outside its accepted values.

429 Too many requests

Monthly quota reached (resets on the 1st at 00:00 UTC), or rate limit exceeded: 10 signatures a minute on Free, 60 on paid plans. Rate limited responses carry a Retry-After header in seconds.

503 Unavailable

Generator temporarily unavailable, retry shortly.

Privacy

Names travel only in request bodies, never in URLs, so they do not end up in access logs. Nothing you send is stored; see the Terms