Documentatie

Dit is de productgerichte referentie voor de openbare API. Dezelfde identiteit, tenant, stijlversie, avatarfamilie, stijlopties, grootte en WebP-output zijn bedoeld om binnen een major-versie stabiel te blijven.

Kern-endpoints

GET /v1/avatar: returns an avatar asset directly
GET /v1/avatar/link: stores the generated avatar in configured object storage and returns signed-link metadata
GET /avatar/<kind>/<identity>/webp: path-style public avatar URL
GET /docs/openapi.json: machine-readable API description

Operationele endpoints

GET /healthz is openbaar voor load balancers en uptimecontroles. GET /metrics is alleen via loopback beschikbaar en retourneert 404 voor niet-lokale peers.

Namespace-ondersteuning

Gebruik tenant en style_version om visuele identiteitsruimtes gescheiden te houden tussen producten of uitrolfases.

GET https://hashavatar.app/v1/[email protected]&tenant=acme&style_version=v2&algorithm=sha512&kind=wizard&background=white&accessory=hat&color=deep-sea-blue&expression=cool&shape=squircle&format=webp&size=256

Anonieme ID's

Stuur een stabiele interne id of een eenrichtingshash van de applicatie in plaats van ruwe persoonsgegevens.

printf '%s' '[email protected]' | sha256sum | cut -d' ' -f1

Rate limits

De openbare dienst past origin-side rate limits toe, met strengere limieten op /v1/avatar/link, directe avatarverzoeken met persist=true en /og.png omdat objectopslagschrijfacties en Open Graph-rendering duurder zijn dan directe rendering.

Timeouts

Avatar-generatie en opslagoperaties zijn begrensd door server-side timeouts zodat dure verzoeken de origin niet onbeperkt kunnen monopoliseren.

Fouten

400: ongeldige kind-waarde, niet-ondersteund algoritme of formaat, grootte of ontbrekende identiteit
408: timeout bij generatie of opslag
429: rate limit overschreden
500: rendering- of opslagfout

OpenAPI

Gebruik voor gegenereerde clients of tooling /docs/openapi.json.