REST API
Libraries (PHP and JavaScript)
Official PHP and JavaScript clients, a Laravel integration and a drop-in web component.
You can call the REST API with any HTTP client, but the official libraries hash the address for you, batch lookups, and turn errors into typed exceptions. Both live in this repository under packages/.
| Library | Install | Use it for |
|---|---|---|
PHP avatarak/avatarak-php |
composer require avatarak/avatarak-php |
any PHP 8.1+ app, with Laravel integration built in |
JavaScript @avatarak/client |
npm install @avatarak/client |
browsers, Node 18+, Deno, Bun. No dependencies |
Keep your API key on the server. Profile lookups need it, so call them from PHP or Node, not from a public web page. Avatar URLs need no key and are safe in the browser.
PHP
use Avatarak\Client;
$avatarak = new Client('avk_YOUR_API_KEY', 'https://avatarak.ir');
// No key, no request: just a URL
$avatarak->avatarUrl('ali@example.com', size: 96, default: 'identicon');
// One profile, or null when there is no public profile
$profile = $avatarak->profile('ali@example.com');
echo $profile?->displayName();
// Many at once: any number of addresses, sent in batches of 100
$profiles = $avatarak->lookup($users->pluck('email')); // [hash => ?Profile]
Profile has typed properties for every field of the API response (nameFa, headline, links, verifiedAccounts, avatarUrl…) and isVerified('github').
Errors are exceptions: AuthenticationException (401), RateLimitException (429, with retryAfter seconds) and the base ApiException.
Laravel
The package is auto-discovered. Add to .env:
AVATARAK_KEY=avk_YOUR_API_KEY
AVATARAK_URL=https://avatarak.ir
use Avatarak\Laravel\Facades\Avatarak;
Avatarak::profile($user->email);
<x-avatarak-avatar :email="$user->email" :size="48" default="identicon" class="rounded-full" alt="" />
The component renders an <img> with a 2× srcset and never writes the address into the page.
JavaScript
import { Avatarak, avatarUrl } from '@avatarak/client';
// Browser or server, no key:
const url = await avatarUrl('ali@example.com', { size: 96, default: 'identicon' });
// Server only, with the key:
const api = new Avatarak({ apiKey: process.env.AVATARAK_KEY, baseUrl: 'https://avatarak.ir' });
const profile = await api.profile('ali@example.com'); // object or null
const many = await api.lookup(['a@x.ir', 'b@y.com']); // { hash: object | null }
Errors: AuthenticationError, RateLimitError (retryAfter) and ApiError. TypeScript types are included.
Web component
For plain HTML pages, no build step:
<script type="module" src="https://unpkg.com/@avatarak/client/src/element.js"></script>
<avatarak-avatar email="ali@example.com" size="48" default="identicon" alt="Ali"></avatarak-avatar>
The address is hashed in the browser and never sent. Attributes: email or hash, size (16–512), default, alt, and base-url for your own install.
Self-hosting
Pass your own server as the base URL (new Client($key, 'https://id.example.com'), baseUrl in JS, or AVATARAK_URL in Laravel). Everything else is identical.