RC ReadyCMS Avatar Resolver
Public documentation for integrators, frontends, and external services.
One URL In. Image Out. Always.

Resolve avatars without caring where they live.

ReadyCMS exposes a single avatar service that always returns an image. It checks the local ReadyCMS avatar first, then external email-based providers, then generated initials, and finally a default image.

See endpoints Copy examples
Primary Route
/avatar
Placeholder Route
/initials
Caching
ETag + immutable PNGs

How resolution works

The public contract is intentionally simple. Callers send one request, and the service walks the fallback chain until it finds something usable.

1

ReadyCMS DB

If an email or legacy custom-field hash is present, the service first checks stored ReadyCMS avatar fields.

2

External provider

If nothing local is available, it tries configured external avatar providers such as Gravatar.

3

Initials avatar

If no photo is found, the service generates a circular initials PNG from name or the email local part.

4

Default image

If nothing else can be resolved, it returns the local default avatar image instead of an error page.

Endpoints

Use query parameters for all public requests. Friendly rewrites are available, so you can call /avatar and /initials directly.

/avatar

Resolver

Returns the best avatar image available for a user. This is the endpoint most integrations should use.

Parameter Purpose
email Primary lookup key for DB resolution and external provider resolution.
name Used for initials fallback when a real image cannot be found.
hash Legacy compatibility for email strings, 64-char custom-field hashes, and 32-char avatar hashes.
size Requested output size when supported by the selected source.
fontSize, space, fontFile Applies only when the request falls through to initials generation.

/initials

Generator

Creates a circular initials avatar PNG. This is useful for direct placeholder generation or previewing how fallbacks will look.

Parameter Purpose
name Preferred initials source. Milos Lukic becomes ML.
email Fallback initials source when name is not provided.
size Output width and height in pixels.
fontSize, space Tunes the initials rendering.
fontFile Optional font selector limited to fonts whitelisted in service configuration.

Copy-paste examples

The examples below use the current host automatically, so you can copy them from the public docs page and adjust values as needed.

Primary avatar request

http://avatar-nur-1.readycms.io/[email protected]&name=John%20Doe

Recommended for most product surfaces. If a real avatar exists, it returns that. If not, it keeps walking the fallback chain.

Legacy email compatibility

http://avatar-nur-1.readycms.io/[email protected]

Older integrations that still send an email in hash continue to work.

Direct initials by name

http://avatar-nur-1.readycms.io/initials?name=Milos%20Lukic

Useful when you want a predictable placeholder without attempting DB or external provider lookups.

Direct initials by email

http://avatar-nur-1.readycms.io/[email protected]

If no name is available, initials are derived from the email local part.

Response behavior

  • Responses are images, not JSON or HTML payloads.
  • Stable image responses include Cache-Control, ETag, and Last-Modified.
  • Generated initials avatars are cached and served as immutable PNGs.
  • External lookups are restricted to https and bounded by redirect and download limits.

Good integration patterns

  • Send both email and name whenever you have them.
  • Prefer /avatar for user-facing surfaces.
  • Use /initials when you explicitly want placeholders only.
  • Let browsers and CDNs cache responses instead of bypassing cache headers.