# Klinio من شيفرتك مباشرة.

شغّل عمليات البحث نفسها التي في الموقع، واستعرض سجلّك، واحصل على الشركات بصيغة JSON. تستخدم الواجهة رصيد حسابك، بما فيه الرصيد اليومي المجاني.

- عنوان URL الأساسي: https://klinio.io/api/v1
- OpenAPI 3.1: https://klinio.io/openapi.json
- خادم MCP: https://klinio.io/api/mcp (https://klinio.io/ar/developers/mcp)
- Access for AI agents: https://klinio.io/auth.md

## بداية سريعة

1. ابدأ بحثًا بتحديد ماذا وأين (query وlocation)، أو برابط يقرؤه Klinio: بحث Google أو خرائط Google، أو دليل Clutch، أو مواقع شركات.
2. تابع حالته. تنتهي معظم عمليات البحث خلال دقائق قليلة، وتظهر الشركات فور العثور عليها.
3. اقرأ الشركات: الموقع والبريد الإلكتروني والهواتف.

```bash

curl -X POST https://klinio.io/api/v1/searches \
  -H "Authorization: Bearer $KLINIO_KEY" -H "Content-Type: application/json" \
  -d '{"query": "web design agencies", "location": "Ankara", "limit": 50}'
curl https://klinio.io/api/v1/searches/SEARCH_ID -H "Authorization: Bearer $KLINIO_KEY"
curl "https://klinio.io/api/v1/searches/SEARCH_ID/results?only=contacts" -H "Authorization: Bearer $KLINIO_KEY"

```

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

أرسل مفتاحك في ترويسة Authorization بالشكل Bearer kl_live_…، وأجسام الطلبات بصيغة JSON. كل استجابة بصيغة JSON.

- `POST /searches`: يبدأ بحثًا. أرسل query وlocation (ماذا وأين: بحث في خرائط Google)، أو link (رابط بحث أو مواقع)، أو websites (قائمة). واختياريًا limit (من 1 إلى 500 شركة) وcountry (حرفان، لرابط بحث google.com).
- `GET /searches`: سجلّك: كل عمليات البحث التي بدأت في الموقع أو في الإضافة أو عبر الواجهة البرمجية، الأحدث أولًا. صفِّه بالمعاملات source وstatus وorigin وq وsince وuntil.
- `GET /searches/{id}`: بحث واحد: حالته وعدد الشركات التي وجدها حتى الآن.
- `GET /searches/{id}/results`: الشركات التي وجدها، 100 في كل مرة (limit حتى 500). يُبقي only=contacts الشركات التي لها بريد إلكتروني أو هاتف، ويجلب next_cursor الصفحة التالية.
- `DELETE /searches/{id}`: يوقف بحثًا في الانتظار أو قيد التشغيل. يبقى ما وجده.
- `GET /account`: خطتك والرصيد المتبقي لك.

## سجلّك موجود في الواجهة البرمجية أيضًا.

كل عملية بحث تبدأها في الموقع أو في إضافة Chrome أو عبر الواجهة البرمجية تُحفظ في السجل نفسه. اعرضه وصفِّه، واقرأ شركات أي بحث من results_url الخاص به.

- `source`: مصدر البحث. linkedin_list قائمة من LinkedIn أُرسلت من الإضافة، وwebsites قائمة مواقع، وmerged قوائم دمجتها في الموقع.
- `status`: حالة البحث. معنى كل حالة موضّح في الأسفل.
- `origin`: أين بدأته: في klinio.io أو في إضافة Chrome أو عبر الواجهة البرمجية.
- `q`: نص يرد في اسم البحث أو في كلماته، دون تمييز بين الأحرف الكبيرة والصغيرة.
- `since`, `until`: بحسب وقت بدء البحث: since من تلك اللحظة، وuntil حتى تلك اللحظة. أرسل تاريخًا (2026-11-01) أو وقتًا بصيغة ISO 8601، والتاريخ في until يشمل اليوم كله.
- `limit`, `cursor`: من 1 إلى 100 بحث في الصفحة (20 إن لم تحدد). للصفحة التالية أرسل next_cursor في cursor، ويعدّ total كل عمليات البحث المطابقة.

## حالة البحث

- `queued`: ينتظر دوره.
- `running`: يجد الشركات ويقرأ مواقعها.
- `completed`: انتهى. فُحصت كل الشركات.
- `stopped`: أوقفته أنت. يبقى ما وجده.
- `failed`: تعذّر إكماله. يوضح الحقل failure السبب.

## الرصيد والحدود

- الرصيد الواحد شركة واحدة لها بريد إلكتروني أو هاتف، كما في الموقع. الشركات التي لم يُعثر لها على شيء مجانية.
- يستهلك الحساب المجاني رصيده اليومي، وتستهلك الباقة رصيدها. عند نفاد الرصيد يجيب البحث الجديد بالرمز 402.
- حتى 3 عمليات بحث في الانتظار أو قيد التشغيل في الوقت نفسه لكل حساب، و120 طلبًا في الدقيقة لكل مفتاح.
- لا يستطيع المتصفح استدعاء الواجهة: فهي لا ترسل ترويسات CORS، لذا يبقى المفتاح على خادمك.

## الأخطاء

يعود الخطأ برمز حالة HTTP وجسم JSON يحتوي على error.code وerror.message.

- `unauthorized`: المفتاح مفقود أو خاطئ أو ملغى.
- `insufficient_credits`: لا يوجد رصيد لبحث جديد.
- `invalid_request`: الجسم أو أحد المعاملات غير صالح.
- `invalid_link`: لا يقرأ Klinio هذا الرابط.
- `mixed_input`: رابط بحث ومواقع في الطلب نفسه.
- `unsupported_google_tab`: تبويب في Google لا يعرض شركات، مثل الصور أو الأخبار.
- `source_disabled`: هذا الموقع معطّل حاليًا.
- `too_many_running`: عمليات بحث كثيرة جدًا في الانتظار أو قيد التشغيل في الوقت نفسه.
- `rate_limited`: طلبات كثيرة جدًا في هذه الدقيقة.
- `not_found`: لا يوجد بحث كهذا في هذا الحساب.
- `not_running`: البحث ليس في الانتظار ولا قيد التشغيل.

- [الأسعار](https://klinio.io/ar/pricing)
- [API](https://klinio.io/ar/developers)
- [خادم MCP](https://klinio.io/ar/developers/mcp)
- [مستخرج البريد من خرائط Google](https://klinio.io/ar/google-maps-email-extractor)
- [باحث البريد في المواقع](https://klinio.io/ar/website-email-finder)
- [مستخرج البريد من بحث Google](https://klinio.io/ar/google-search-email-extractor)
- [مستخرج البريد من Clutch](https://klinio.io/ar/clutch-email-extractor)
- [باحث الشركات في LinkedIn](https://klinio.io/ar/linkedin-company-email-finder)
- [خصوصية الإضافة](https://klinio.io/ar/extension-privacy)

---
Page: https://klinio.io/ar/developers
Markdown: https://klinio.io/ar/developers.md
