مرجع API | Wambesha

مرجع API متوفر باللغة الإنجليزية فقط.

مرجع API — v1

https://api.wambesha.com · مصادقة Bearer · JSON

كل نقطة نهاية في v1، مع معاملاتها، ومثال على الطلب والاستجابة، والأخطاء التي قد تُرجعها. أوصاف نقاط النهاية باللغة الإنجليزية.

سجل التغييرات

المصادقة

Your API key, presented as a Bearer token. Keys are per-account and carry a plan; the plan decides which endpoints answer and what your quota is. Never embed a key in a browser client — it is a credential, and a browser cannot keep one.

HTTP

Authorization: Bearer $WAMBESHA_API_KEY

حيثما تقبل نقطة النهاية مفتاح العرض التجريبي العام، يتضمنه مقتطف «جرّبها» الخاص بها، لذا يعمل كما هو؛ أما أي مقتطف آخر فيحتاج إلى مفتاحك الخاص. مفتاح العرض التجريبي مخصص لتجربة API فقط: يتغيّر يوميًا، ويمكن إيقافه في أي وقت، ويجب ألا يُستخدم أبدًا في بيئة الإنتاج. استخدم مفتاحك الخاص لأي شيء تبنيه.

ترويسات الاستجابة

X-Request-IDكل استجابة مصادَق عليها
The id of this request, on every response - success or error. Quote it to support: it is how we find your request in our logs. An X-Request-ID you send is honoured and echoed back, so you can use your own; otherwise we generate one. /v1 error bodies carry no trace id of their own.
X-Quota-Resetكل استجابة مصادَق عليها
RFC 3339 instant at which the billing period rolls. Present on every response to a request whose key was metered - every 2xx, every error a handler returned, and the quota 429. Absent on a refusal that happens before metering: a missing or unknown key (401), a restricted key or a plan that does not carry the endpoint (403), a public demo-key gate refusal, and the pre-authentication flood throttle.
X-Calls-Remainingكل استجابة مصادَق عليها
Requests left in the period after this one, never below 0. Present whenever X-Quota-Reset is (see there for when a response carries no quota headers).
X-Verifications-Remainingكل استجابة مصادَق عليها
How many verifications you can still make before a limit stops you. The daily limit and the monthly allowance are counted separately; this is whichever of the two runs out first. Sent whenever X-Quota-Reset is.
X-Quota-Graceكل استجابة مصادَق عليها
true when THIS request fell inside the 10% grace band above a monthly ceiling. A grace request is served and is not billed; treat true as "back off now", not as headroom. Always true or false, never absent when the other quota headers are present.
Retry-Afterعند الاستجابة 429 فقط
Seconds to wait before retrying. On every 429 - the quota hard stop, the public demo key's limits, and the pre-authentication flood throttle (which carries this header alone, because no key has been read yet).
X-Demo-Challenge-Modeمع مفتاح العرض التجريبي فقط
Sent only on responses to the public demo key. The value interactive asks the documentation page to show the visible verification widget - it is sent once a browser has made more than five runs in ten minutes or has received a 429. The page then repeats the header, X-Demo-Challenge-Mode: interactive, on its next request, with the widget's token in X-Demo-Challenge. Requests made with your own key never receive it.

الأخطاء

لكل خطأ الجسم نفسه: حالة HTTP، ورمز ثابت يمكنك التفرع بناءً عليه، ورسالة موجّهة للأشخاص، وأخطاء الحقول عندما تكون قيمة ما خاطئة. للإشارة إلى طلب معيّن عند التواصل معنا، استخدم ترويسة الاستجابة X-Request-ID الخاصة به.

استجابة مسجّلة

Content-Type: application/json
X-Request-ID: 5f3c9a1e7b2d4c60

GET/v1/search

{
  "timestamp": "2026-09-27T12:00:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Enter at least 2 characters to search.",
  "path": "/v1/search",
  "errors": [
    {
      "field": "q",
      "rejectedValue": "a",
      "message": "Enter at least 2 characters to search."
    }
  ],
  "metadata": {
    "errorCode": "CATALOG_SEARCH_QUERY_TOO_SHORT"
  },
  "code": "validation-failed"
}

400

validation-failed400405
The request is not one this operation accepts - a parameter outside its rule, a missing required parameter, an unsupported language, or a method the route does not take.
ما يجب فعلهFix the request; errors names the parameter. Retrying it unchanged fails the same way.
cursor-invalid400
The cursor is malformed, stale, from a different filter set or sort, or past what your key may page.
ما يجب فعلهDrop the cursor and request the first page again.
unauthenticated401
No key, or a key that is unknown, malformed, expired or revoked - one answer for all of them. Also what a switched-off public demo key answers.
ما يجب فعلهSend a valid key as Authorization: Bearer <key>; if it was rotated, use its replacement.
forbidden403
The key is valid but a restriction its owner set - a scope, an IP allowlist, a referrer allowlist - excludes this request. Also a key rotating a key other than itself.
ما يجب فعلهCall from an allowed place or change the key's restrictions in the console.
plan-required403
Your plan does not include this operation or this freshness, or the public demo key was used for something it cannot reach.
ما يجب فعلهUpgrade the plan, or use your own key rather than the demo key.
challenge-required403
A browser call with the public demo key carried no valid bot-check token.
ما يجب فعلهComplete the check on the page and run the request again. Not sent to paying keys.
not-found404
Nothing matches the reference, or the reference is not a valid id.
ما يجب فعلهCheck the id; a merged record answers 200 with its survivor, so 404 means it never existed here.
conflict409
The request contradicts current state - a key already rotated, revoked or expired, or an identifier that matches several records.
ما يجب فعلهRead metadata.errorCode; rotate the replacement key, or disambiguate the identifier.
gone410
The record existed and has been removed. No reason is given, by design.
ما يجب فعلهDrop it from your mirror; /v1/changes reports it as removed.
quota-exhausted429
A plan ceiling is reached - requests (daily or monthly) or verifications. The message names which.
ما يجب فعلهWait for Retry-After (the daily window resets at midnight UTC, the monthly one at X-Quota-Reset), or upgrade. The refused call is not charged.
rate-limited429
Too many requests too fast - the per-address flood throttle, or the public demo key's own limits, temporary blocks and in-flight cap.
ما يجب فعلهWait Retry-After seconds, then slow down.
upstream-unavailable503
We could not meter or serve the request right now. Never served unmetered, never charged.
ما يجب فعلهRetry with exponential backoff.

إدارة الإصدارات

لا يتضمن v1 أي تغييرات غير متوافقة أبدًا: المسارات والمعاملات المطلوبة وحقول الاستجابة لا تتغير ضمن v1. يمكن إضافة حقول ونقاط نهاية جديدة، ويُعلَن عنها أولًا في سجل التغييرات. كيف يعمل نظام الإصدارات

نقاط النهاية

Discovery

Titles

People

Changes

Account