API

مرجع واجهة كلمات المرور البرمجية

مرجع api.password.es: كل معامِل، وكل حقل في الاستجابة، وكل رمز خطأ، والحدود. والأمثلة تُلصق في الطرفية كما هي.

إن كنت تبحث عمّا هذا، ولمن، ومتى يُستحسن ألا تستخدمه، فابدأ من صفحة الواجهة البرمجية.

نقاط النهاية

كل شيء تحت https://api.password.es. اثنتان تستجيبان وواحدة لم تستجب بعد — وتلك تقولها في استجابتها نفسها.

POST/v1/generate يولّد كلمة مرور واحدة أو أكثر ويعيد تحليلها.
GET/openapi.json وصف الواجهة البرمجية بصيغة OpenAPI 3.1.
POST/mcp خادم MCP للمساعدين. أداة واحدة: generate_password.
POST/v1/check 501 لا وجود له بعد. الخطأ يقول ما الذي ينقص وإلى أين تذهب في هذه الأثناء.

توليد كلمة مرور

الجسم اختياري: من دونه تخرج ١٦ محرفًا بأنواع المحارف الأربعة كلها مفعَّلة. ومعه، ما تطلبه أنت.

الطلب

curl -X POST https://api.password.es/v1/generate \
  -H 'content-type: application/json' \
  -d '{"length":20,"exclude_ambiguous":true}'

الاستجابة

{
  "passwords": [
    "P#f.aK+w4pcsx]}Gx;*>"
  ],
  "analysis": {
    "length": 20,
    "pool": 83,
    "bits": 127.50078862693852,
    "log10_guesses": 38.08053185185735,
    "crack_time_log10_seconds": 26.08053185185735,
    "crack_time": {
      "value": "3.8 × 10¹⁸",
      "unit": "years"
    },
    "level": 4,
    "level_scale": "time",
    "ceiling": false
  },
  "notice": "Generated on someone else's machine, which is a security antipattern even though we store nothing. For a password you will actually use, the generator at https://password.es/en/ runs entirely in your browser and sends nothing.",
  "_meta": {
    "plan": "anonymous",
    "lang": {
      "messages": "en",
      "links": "en"
    },
    "limits": {
      "burst": {
        "limit": 60,
        "window_seconds": 60
      }
    },
    "quota": {
      "limit": null,
      "remaining": null,
      "reset": "2026-09-01T00:00:00.000Z"
    },
    "docs": "https://password.es/api/"
  }
}

المعامِلات

كلها اختيارية. الجدول بالإنجليزية وهو نفسه في اللغات الثماني عشرة، عن قصد: من يدمج واجهة برمجية يكتب أسماء الحقول كما تُكتب تمامًا، وثماني عشرة ترجمة لكلمة exclude_ambiguous ستكون دَينًا لا نطاقًا.

Field	Type	Default	Notes
length	integer 4–64	16	How many characters. The same range as the generator on this site.
count	integer 1–20	1	How many passwords to return. `passwords` is always an array, including with `count` 1.
lower	boolean	true	Include a–z (26 characters).
upper	boolean	true	Include A–Z (26 characters).
digits	boolean	true	Include 0–9 (10 characters).
symbols	boolean	true	Include `~!@#$%^&*()_+-=[]{};:,./<>?` — the same 27 as the slider on the home page, no more.
exclude_ambiguous	boolean	false	Drops `0 O 1 I l \| o`. Six of them in practice, not seven: `\|` is not in the symbol set to begin with. That is why `pool` reads 83 above instead of 89.
no_repeats	boolean	false	Avoids adjacent repeated characters. Not an absolute guarantee: it retries ten times, exactly as the web generator does. At length 64 that lets a repeat through about 0.1% of the time.
lang	string	`en`	Which language to answer in. One of the site's eighteen. Also accepted as `?lang=` in the URL, which wins over this field; without either, `Accept-Language` is read. An unknown value is not an error — it falls back to English. See the section below: messages exist in English and Spanish, links in all eighteen.

ماذا يعني كل رقم

الفكرة نفسها: المرجع بالإنجليزية والشرح إلى جانبه. ولا واحد من هذه الأرقام جديد — كلها تخرج من المحرك نفسه الذي يرسم المؤشر في الصفحة الرئيسية.

Field	Notes
passwords	An array of strings, always — including with `count` 1.
analysis.length	How many characters came back.
analysis.pool	The size of the alphabet the password was drawn from.
analysis.bits	`H = L·log2(N)`, the same formula as the home page. With `no_repeats` it becomes `log2(N)+(L-1)·log2(N-1)`.
analysis.log10_guesses	The expected work, as a base-10 logarithm: half the keyspace.
analysis.crack_time_log10_seconds	At 10¹² guesses/s, offline, fast hash. The same attack model as the rest of the site.
analysis.crack_time	The same figure in words. `unit` follows the answer language: `years`, `años`…
analysis.level	0–4. The same scale as the checker, ever since the site unified the two it used to have.
analysis.level_scale	`"time"`. Says where the level came from, so that a future divergence is visible instead of having to be inferred by comparing numbers.
analysis.ceiling	`false`: the server generated the password, so the figure is exact and not a ceiling. The same flag the checker uses.
notice	The antipattern warning, in every single response.
_meta.plan	`"anonymous"`. The only lane there is; the others arrive with accounts.
_meta.lang	`{ "messages", "links" }` — which language each half actually came back in. They can differ, and that is why the API says so instead of leaving you to guess.
_meta.limits.burst	The rate limit actually enforced: `limit` requests per `window_seconds`.
_meta.quota	The reserved daily-quota slot. `limit` and `remaining` are `null` because nobody counts daily requests yet.
_meta.docs	A link back to the documentation.

لغة الاستجابة

تستجيب افتراضيًا بالإنجليزية، وهو ما يتوقعه من يدمجها دون أن يقول شيئًا. وتتغير بثلاث طرق، وإذا تعارضت غلبت الأولى: ?lang= في المسار، و"lang" في الجسم، وترويسة Accept-Language.

وهنا عدم تماثل يحسن معرفته: الرسائل موجودة بالإنجليزية والإسبانية؛ أما الروابط فبلغات الموقع الثماني عشرة كلها. فطلب الألمانية يعطيك روابط بالألمانية ورسائل لا تزال بالإنجليزية.

الطلب

curl -X POST 'https://api.password.es/v1/generate?lang=de' \
  -H 'content-type: application/json' \
  -d '{"length":20}'

الاستجابة

"_meta": {
  "lang": { "messages": "en", "links": "de" }
}

ولا حاجة إلى التخمين: كل استجابة تعلن في _meta.lang ما طُبِّق على كل نصف. ولغة غير موجودة ليست خطأ — تسقط إلى الإنجليزية، و_meta.lang يقول ذلك.

فحص كلمة مرور: ليس بعد

/v1/check يعيد 501. ليس خللًا ولا سهوًا: هو مقصود، والاستجابة تشرح ما الذي ينقص وإلى أين تذهب في هذه الأثناء. وchecker_url يشير إلى فاحص الموقع باللغة التي طلبتها.

الطلب

curl -X POST https://api.password.es/v1/check \
  -H 'content-type: application/json' \
  -d '{"password":"x"}'

الاستجابة

{
  "error": "not_implemented",
  "message": "/v1/check does not exist yet. Returning the same numbers as the password.es checker requires its very same pattern engine, and that costs between 11 ms and 3.6 s of CPU per request depending on the input: it is waiting on a plan cap decision and on a length cap. Meanwhile the web checker does exactly this in your browser, sending nothing: https://password.es/en/checker/",
  "checker_url": "https://password.es/en/checker/",
  "docs": "https://password.es/api/",
  "_meta": { "…": "igual que arriba" }
}

الأخطاء

كلها بالشكل نفسه: error قصير بمنزلة الرمز، وmessage بلغة واضحة —وهو ما يقرأه مساعد الذكاء الاصطناعي على مستخدمه—، وأحيانًا field الذي سبّبه، وdocs، و_meta المعتاد نفسه.

HTTP	error	Notes
400	`invalid_length`	`length` outside 4–64. `field` names it.
400	`invalid_count`	`count` outside 1–20. `field` names it.
400	`empty_alphabet`	All four character types turned off, so there is no alphabet to draw from. No `field`: it is the combination, not one parameter.
400	`unknown_parameter`	A parameter this endpoint does not accept. `field` gives the offending name.
429	`rate_limited`	Over 60 requests in a minute. Carries `Retry-After` and `RateLimit-*` headers, and `limit` / `window_seconds` in the body.
501	`not_implemented`	Only from `/v1/check`. Carries `checker_url`, pointing at the web checker in the answer language.

الحدود

حدٌّ واحد، وهو الذي يُطبَّق فعلًا: ستون طلبًا في الدقيقة لكل عنوان IP. لا حاجة لتصديق هذه الصفحة: الرقم يسافر مع كل استجابة، داخل _meta.limits.burst.

عند تجاوزه تكون الاستجابة 429 مع Retry-After وترويسات RateLimit-*، ومعها رسالة بلغة واضحة تقول ما العمل. ولا تحمل رابطًا إلى تسجيل ولا إلى أسعار، لأنه لا تسجيل ولا أسعار.

في _meta سترى كذلك كتلة quota وقيمتاها كلتاهما null. هذا مقصود: إنه المكان المحجوز ليوم تُوجد فيه الحسابات، وهو فارغ لأن أحدًا اليوم لا يعدّ الطلبات اليومية. حدٌّ يُعلَن ولا يُطبَّق أسوأ من ألا تعلن حدًّا أصلًا.

خادم MCP

‏MCP هو البروتوكول الذي يستخدمه مساعدون مثل Claude أو ChatGPT للوصول إلى أدوات خارجية. اربط هذا العنوان بمساعدك وسيولّد كلمات مرور بالأرقام نفسها بدل اختلاقها. بلا تسجيل وبلا مفتاح، وبالحد نفسه: 60 طلبًا في الدقيقة.

إنه خادم بلا حالة، ومن المفيد معرفة ذلك إن كنت قادمًا من خوادم MCP أخرى: يُجاب على POST بـ JSON دون فتح أي بث، ولا يُصدر Mcp-Session-Id ولا يُنتظر، ويُجاب على الإشعار بـ 202 بلا متن، ويعيد GET رمز 405. ومواصفة 2025-06-18 تسمح بذلك صراحةً.

curl -X POST https://api.password.es/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"generate_password",
                 "arguments":{"length":20,"lang":"es"}}}'

ينشر أداة واحدة فقط، وهي generate_password، بالمعامِلات نفسها الواردة في الجدول أعلاه مضافًا إليها lang. لا توجد check_password_strength ولن توجد ما دام /v1/check غير موجود: الأداة التي تعيد خطأً دائمًا ليست أداة، بل وعد مكسور داخل فهرس المساعد.

التنبيه إلى أن هذا نمط مضاد يسافر في وصف الأداة وفي كل نتيجة. وهذا مقصود: فهو ما ينتهي المساعد إلى قراءته على من طلب كلمة المرور.

الوثائق التي تقرأها الآلات

إلى جانب هذه الصفحة يوجد وصف بصيغة OpenAPI 3.1، وهذا منشور فعلًا: api.password.es/openapi.json. هو ما يقرأه مولّد عملاء، أو محرِّر بإكمال تلقائي، أو وكيل يريد أن يعرف ما الحقول الموجودة من دون أن يخبره أحد. يصف المعامِلات نفسها التي في الجدول أعلاه، ورموز الأخطاء، وسبب كون quota فارغة.