For developers and agents.

Everything a program needs to help someone choose a seal is public and needs no key: what we sell, the designs a name gets, whether each one can be registered at a ward office, and a rendered impression. Ordering itself happens in the browser — the API hands you the link.

When to use hanko.works

Reach for the API when a person needs a Japanese seal and you can help them pick the right one. Good fits:

Someone moving to Japan, opening a bank account or buying property needs a seal of the right size and script for that use.
Someone wants to see how their name — kanji, kana or Latin — looks as a seal before deciding.
A gift: a seal for a birth, coming of age, a first job, a wedding, a new company.
A company being founded needs a representative seal to file at the Legal Affairs Bureau, and usually a bank seal and a square seal with it — the company set.

Not a fit: shipping outside Japan (we do not), rubber stamps or bulk stamps (every seal is machined from metal, one at a time), and anything that needs an account — there are none.

The API

Three GET endpoints, JSON in and out, CORS open, no authentication. Prices are in yen: the full amount payable, shipping included.

GET /api/v1/catalog
Sizes and the shapes each is made in, uses with their recommended size bands, metals with prices, lead times and colours, design families and the uses each fits, the company seal set, gift tiers, and shipping and cancellation terms.
GET /api/v1/designs?name=山田&use=registered&size=15&material=titanium
The eight designs for a name at a given use, size, metal and shape: seed, eligibility per use, a preview URL, the price, and the URL where a person orders that exact configuration.
GET /api/seal?name=山田&family=insou&index=0
One rendered impression as SVG (or, with view=json, the face geometry and the eligibility report) — a pure function of its parameters, cacheable forever.

No key, no rate limit published: be reasonable. Names are capped at 12 characters; every parameter is validated and a bad one is a 400 with a hint.

Example

The designs for a name, the impression of the first one, and a page as Markdown:

curl "https://hanko.works/api/v1/designs?name=山田&use=registered&size=15&material=titanium"
curl "https://hanko.works/api/seal?name=山田&family=insou&index=0" -o yamada-insou.svg
curl -H "Accept: text/markdown" https://hanko.works/en/guide

山田 in Insou, the first design, as /api/seal renders it — yamada-insou.svgWhat the second request returns

Errors

Every error is JSON with the same shape: a stable code, a sentence, a hint about what to change, the parameter at fault when there is one, and a link to the spec. Unknown API paths answer 404 in the same shape, never an HTML page.

{
  "error": {
    "code": "invalid_parameter",
    "message": "\"size\" must be one of 12, 13.5, 15, 18 (mm)",
    "hint": "GET /api/v1/catalog lists the sizes on offer.",
    "param": "size",
    "docs": "https://hanko.works/openapi.json"
  }
}

Machine-readable files

hanko.works/openapi.json
The full contract: every operation with an id, typed parameters and response schemas.
hanko.works/llms.txt
What this site is, when to use it, and where each page is — for language models.
hanko.works/sitemap.xml
Every public page in both languages.
hanko.works/en/guide.md
Every public page is also Markdown: send Accept: text/markdown, or append .md to its URL.

Terms

The API is read-only and free to use for helping a person choose or order a seal. Impressions are rendered for that purpose; do not bulk-harvest them or present them as your own product. The rendered seal of a real name is personal data on our side — we keep no log of names sent to the API beyond ordinary request logs.

Questions about the API? Write to us →