# مرجع واجهة كلمات المرور البرمجية · password.es

> كل معامِلات POST /v1/generate، وكل حقل في الاستجابة، ورموز الأخطاء وحدود api.password.es. مع مثال curl يعمل فعلًا.

password.es · Original: https://password.es/ar/api/docs/

---

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

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

إن كنت تبحث عمّا هذا، ولمن، ومتى يُستحسن *ألا* تستخدمه، فابدأ من [صفحة الواجهة البرمجية](https://password.es/ar/api/).

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

كل شيء تحت `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^12 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](https://api.password.es/openapi.json). هو ما يقرأه مولّد عملاء، أو محرِّر بإكمال تلقائي، أو وكيل يريد أن يعرف ما الحقول الموجودة من دون أن يخبره أحد. يصف المعامِلات نفسها التي في الجدول أعلاه، ورموز الأخطاء، وسبب كون `quota` فارغة.