{"openapi":"3.1.0","info":{"title":"درب — واجهة البيانات العامّة","version":"1.0.0","summary":"بياناتُ القبول الجامعي السعودي للقراءة الآلية.","description":"منصّة تعليمية سعودية تُهيّئ الطالب لاختبارات القدرات والتحصيلي وستيب وبرامج أرامكو، وتساعده على اختيار جامعته وتخصّصه: خريطة مذاكرة، جلسات تركيز، خزنة أخطاء، تقويم دراسي رسمي، ودليل جامعات سعودية بكلياتها وتخصّصاتها.\n\nواجهاتٌ للقراءة فقط، عامّة بلا مصادقة. لا تُعيد أي بيانات شخصية للطلاب. الحقولُ الفارغة تعني «لم تُعلنه الجهة الرسمية بعد» — لا تُملأ تخميناً.","contact":{"name":"درب","url":"https://usedarb.com","email":"support@usedarb.com"},"license":{"name":"Proprietary","url":"https://usedarb.com/terms"},"termsOfService":"https://usedarb.com/terms"},"servers":[{"url":"https://usedarb.com","description":"الإنتاج"}],"externalDocs":{"description":"توثيق الواجهة","url":"https://usedarb.com/docs/api"},"tags":[{"name":"universities","description":"قائمة الجامعات السعودية ومعلوماتها؛ ومع `id` تُعاد كلياتها وتخصّصاتها الدقيقة."},{"name":"exams","description":"الاختبارات الوطنية ونوافذ تسجيلها الرسمية وحالتها (مفتوح/قادم/بانتظار الإعلان)."},{"name":"calendar","description":"التقويم الدراسي السعودي المعتمد: الفصول والإجازات ونهاية العام."},{"name":"faq","description":"الأسئلة الشائعة عن القبول الجامعي ومنصّة قبول، مع بحثٍ نصّي عبر `q`."}],"paths":{"/api/agent/universities":{"get":{"tags":["universities"],"operationId":"listUniversities","summary":"قائمة الجامعات السعودية ومعلوماتها؛ ومع `id` تُعاد كلياتها وتخصّصاتها الدقيقة.","parameters":[{"name":"id","in":"query","required":false,"schema":{"type":"string"},"description":"معرّف جامعة — يُعيد كلياتها وتخصّصاتها الدقيقة"},{"name":"region","in":"query","required":false,"schema":{"type":"string"},"description":"تصفية بالمنطقة"}],"responses":{"200":{"description":"نجاح","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"universities":{"type":"array","items":{"$ref":"#/components/schemas/University"}},"university":{"$ref":"#/components/schemas/UniversityDetail"}}}}}}}}},"/api/agent/exams":{"get":{"tags":["exams"],"operationId":"listExams","summary":"الاختبارات الوطنية ونوافذ تسجيلها الرسمية وحالتها (مفتوح/قادم/بانتظار الإعلان).","responses":{"200":{"description":"نجاح","content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string"},"exams":{"type":"array","items":{"$ref":"#/components/schemas/Exam"}}}}}}}}}},"/api/agent/calendar":{"get":{"tags":["calendar"],"operationId":"getCalendar","summary":"التقويم الدراسي السعودي المعتمد: الفصول والإجازات ونهاية العام.","responses":{"200":{"description":"نجاح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcademicCalendar"}}}}}}},"/api/agent/faq":{"get":{"tags":["faq"],"operationId":"searchFaq","summary":"الأسئلة الشائعة عن القبول الجامعي ومنصّة قبول، مع بحثٍ نصّي عبر `q`.","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"بحثٌ نصّي"}],"responses":{"200":{"description":"نجاح","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"faq":{"type":"array","items":{"$ref":"#/components/schemas/FaqItem"}}}}}}}}}},"/api/agent/skills":{"get":{"tags":["skills"],"operationId":"listSkills","summary":"اكتشاف المهارات المتاحة للوكلاء","responses":{"200":{"description":"نجاح","content":{"application/json":{"schema":{"type":"object","properties":{"skills":{"type":"array","items":{"type":"object"}}}}}}}}}},"/mcp":{"post":{"tags":["mcp"],"operationId":"mcpJsonRpc","summary":"خادم MCP — JSON-RPC 2.0 (initialize · tools/list · tools/call · prompts · resources)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","integer","null"]},"method":{"type":"string"},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"نجاح","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","integer","null"]},"result":{"type":"object"},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}}}}}},"components":{"schemas":{"University":{"type":"object","title":"University","description":"جامعةٌ سعودية كما تظهر في دليل درب.","required":["id","name","url"],"properties":{"id":{"type":"string","description":"معرّفٌ ثابت (مثل «kfupm»)"},"name":{"type":"string","description":"الاسم الرسمي بالعربية"},"region":{"type":["string","null"],"description":"المنطقة الإدارية"},"kind":{"type":["string","null"],"description":"حكومية أو أهلية"},"qsRank":{"type":["integer","null"],"description":"ترتيب QS العالمي"},"qsRankTo":{"type":["integer","null"],"description":"نهاية النطاق حين يُنشر ترتيباً نطاقياً"},"qsYear":{"type":["integer","null"],"description":"سنة إصدار الترتيب"},"url":{"type":"string","format":"uri","description":"صفحة الجامعة في درب"}}},"UniversityDetail":{"type":"object","title":"UniversityDetail","description":"جامعةٌ مع كلياتها وتخصّصاتها الدقيقة.","allOf":[{"$ref":"#/components/schemas/University"}],"properties":{"colleges":{"type":"array","description":"كليات الجامعة، ولكل كلّيةٍ تخصّصاتها","items":{"type":"object","required":["name","majors"],"properties":{"name":{"type":"string"},"majors":{"type":"array","items":{"type":"string"}}}}},"majorsCount":{"type":"integer","description":"مجموع التخصّصات في الجامعة"}}},"ExamWindow":{"type":"object","title":"ExamWindow","description":"نافذةُ تسجيلٍ رسمية لاختبارٍ وطني. الحقولُ الفارغة تعني أن الجهة لم تُعلن الموعد بعد — لا تُملأ تخميناً.","required":["id","label","announced"],"properties":{"id":{"type":"string"},"label":{"type":"string","description":"اسم النافذة كما تعلنه الجهة"},"registrationStart":{"type":["string","null"],"format":"date"},"registrationEnd":{"type":["string","null"],"format":"date"},"examStart":{"type":["string","null"],"format":"date"},"examEnd":{"type":["string","null"],"format":"date"},"announced":{"type":"boolean","description":"هل أُعلن أيُّ تاريخٍ لهذه النافذة؟"}}},"Exam":{"type":"object","title":"Exam","description":"اختبارٌ وطني (قدرات · تحصيلي · ستيب) ونوافذُ تسجيله.","required":["id","hasOfficialDates","windows"],"properties":{"id":{"type":"string","description":"معرّف المسار"},"hasOfficialDates":{"type":"boolean"},"alwaysOpen":{"type":"boolean","description":"تسجيلٌ مفتوحٌ طوال العام"},"windows":{"type":"array","items":{"$ref":"#/components/schemas/ExamWindow"}}}},"AcademicCalendar":{"type":"object","title":"AcademicCalendar","description":"التقويم الدراسي السعودي المعتمد: الفصول والإجازات وحدود العام.","required":["updatedFor","years"],"properties":{"updatedFor":{"type":"string","description":"العام الذي حُدِّث له التقويم"},"years":{"type":"array","items":{"type":"object","required":["id","schoolStart","schoolEnd","periods"],"properties":{"id":{"type":"string","description":"العام الهجري (مثل «1448»)"},"gregorianLabel":{"type":"string","description":"ما يقابله ميلادياً"},"schoolStart":{"type":"string","format":"date"},"schoolEnd":{"type":"string","format":"date"},"source":{"type":"string","description":"الجهة التي أعلنت التقويم"},"periods":{"type":"array","items":{"type":"object","required":["kind","label","start","end"],"properties":{"kind":{"type":"string","description":"فصلٌ دراسي أو إجازة"},"label":{"type":"string"},"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"}}}}}}}}},"FaqItem":{"type":"object","title":"FaqItem","description":"سؤالٌ شائع عن القبول الجامعي ومنصّة قبول.","required":["id","question","answer"],"properties":{"id":{"type":"string"},"question":{"type":"string"},"answer":{"type":"string"},"category":{"type":"string"}}}},"securitySchemes":{"googleOAuth":{"type":"oauth2","description":"دخولُ Google عبر Firebase — للوصول إلى ما يخصّ حساب طالبٍ بعينه، بإذنه.","flows":{"authorizationCode":{"authorizationUrl":"https://accounts.google.com/o/oauth2/v2/auth","tokenUrl":"https://oauth2.googleapis.com/token","scopes":{"openid":"الهوية","email":"البريد","profile":"الملف العام"}}}},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Firebase ID token"}}},"security":[]}