# مرجع API

> يكشف ClearLogo عن نقطة نهاية HTTP واحدة، `GET /logo/{domain}`، التي تُرجع صورة PNG (أو WebP/JPEG) لشعار المجال بنسبة ثابتة وخلفية شفافة. الاستخدام المجهول يعمل للاختبار منخفض الحجم؛ تستخدم حركة الإنتاج مفتاح متصفح (عميل) أو مفتاح خادم (خلفية).

## نقطة النهاية

```
GET https://api.clearlogo.dev/logo/:domain
```

`:domain` هو اسم مضيف بدون مخطط أو مسار، على سبيل المثال `github.com`. تُرجع API صورة `image/png` بشكل افتراضي.

## معاملات الاستعلام

| الاسم | النوع | القيمة الافتراضية | ملاحظات |
| --- | --- | --- | --- |
| `size` | number | `128` | بُعد النتيجة بالبكسل. مربع فقط. القيم المسموح بها: 16، 32، 48، 64، 96، 128، 192، 256، 512، 1024. |
| `content` | number | `80` | أثر الشعار داخل الكانفاس (50–100، خطوة 5). |
| `format` | `png \| webp \| jpeg` | `png` | صيغة الإخراج. يُتفاوض تلقائياً من خلال رأس `Accept` — تتلقى المتصفحات الحديثة WebP تلقائياً عبر `<img>`. |
| `theme` | `light \| dark` | `light` | يُرجع المتغير الداكن عند توفره، وإلا يُرجع الفاتح. |
| `token` | string | — | مفتاح المتصفح المستخدم من كود العميل. يجب أن يطابق Origin أو Referer مجالاً مسموحًا في المفتاح. |

## المصادقة

تعمل الطلبات المجهولة لاختبار منخفض الحجم. لحركة الإنتاج استخدم مفتاح متصفح (عميل) أو مفتاح خادم (خلفية):

**المتصفح**

```html
<img
  src="https://api.clearlogo.dev/logo/example.com?token=YOUR_BROWSER_KEY"
  alt="" />
```

**الخادم**

```bash
curl \
  -H "Authorization: Bearer YOUR_SERVER_KEY" \
  "https://api.clearlogo.dev/logo/example.com"
```

## تحديد المعدل

يتم إرجاع حدود لكل مفتاح في رؤوس `X-RateLimit-*`. عند تجاوزها يرد API برمز `429` ويتضمن تلميح `Retry-After`.

## الأسئلة الشائعة

### كيف أحصل على شعار لمجال؟

أرسل طلب GET إلى `https://api.clearlogo.dev/logo/{domain}` حيث `{domain}` هو اسم مضيف مثل `github.com`. لا يلزم تسجيل الدخول لاختبار منخفض الحجم. الاستجابة هي PNG افتراضياً وتعمل مباشرة في علامات `<img>`.

### ما الفرق بين مفتاح المتصفح ومفتاح الخادم؟

مفتاح المتصفح آمن للنشر في كود الواجهة الأمامية وعلامات `<img>`؛ يتم التحقق من الطلبات مقابل المجالات المسموح بها التي تكوّنها في المفتاح. مفتاح الخادم يُصادق عبر رأس `Authorization: Bearer` من خلفيتك ويجب ألا يصل أبداً إلى المتصفح.

### ما صيغ الإخراج المدعومة؟

`png` (افتراضي)، `webp`، و `jpeg`. عند حذف معامل `format`، يتفاوض ClearLogo على المحتوى من رأس طلب `Accept` — تتلقى المتصفحات الحديثة WebP تلقائياً عند تحميل API عبر علامة `<img>`.