{ "openapi": "3.1.0", "info": { "title": "Aleem AI Web Crawler API", "version": "1.0.0", "summary": "«عليم زاحف الويب» — web collector, interpreter and researcher", "description": "Aleem AI Web Crawler's REST API. Compatible with the core Firecrawl v2 endpoints listed in the compatibility table (/docs/compatibility). متوافق مع نقاط Firecrawl v2 الأساسية الموضحة في جدول التوافق. Aleem AI Web Crawler extras: `mode` (fast | extended | deep | custom), per-request `settings`, and the credits actually used on every response (`creditsUsed`). Firecrawl is a trademark of its owner; Aleem AI Web Crawler is not affiliated with it.", "contact": { "name": "Trusted Intelligence — شركة الذكاء الموثوق", "url": "https://web-crawler.aleem-ai.com" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://web-crawler.aleem-ai.com" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Scrape", "description": "جلب صفحة" }, { "name": "Batch", "description": "دفعات" }, { "name": "Crawl", "description": "زحف" }, { "name": "Map", "description": "خريطة الموقع" }, { "name": "Search", "description": "بحث" }, { "name": "Extract", "description": "استخراج منظم" }, { "name": "Research", "description": "وكيل البحث" }, { "name": "Account", "description": "الحساب والاستهلاك" }, { "name": "Settings", "description": "الإعدادات" }, { "name": "Browser", "description": "متصفح الوكيل" }, { "name": "Devices", "description": "الأجهزة المقترنة" }, { "name": "Billing", "description": "الرصيد والفوترة" }, { "name": "Admin", "description": "الإدارة" }, { "name": "System", "description": "النظام" }, { "name": "v1 aliases", "description": "أسماء v1 البديلة" } ], "paths": { "/health": { "get": { "tags": [ "System" ], "operationId": "health", "summary": "Service health (no auth)", "description": "حالة الخدمة دون مصادقة", "security": [], "responses": { "200": { "description": "Health", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "product": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "time": { "type": "string" }, "bindings": { "type": "object", "properties": { "db": { "type": "boolean" }, "cache": { "type": "boolean" }, "jobs": { "type": "boolean" }, "browser": { "type": "boolean" }, "ai": { "type": "boolean" } } }, "llm": {}, "origin": { "type": [ "boolean", "null" ], "description": "null when no origin is configured" }, "modes": { "type": "object" } } }, "example": { "status": "ok", "product": "zahif-v1.0.0", "name": "عليم زاحف الويب", "version": "1.0.0", "bindings": { "db": true, "cache": true, "jobs": true, "browser": true, "ai": true }, "origin": null } } } } } } }, "/bot": { "get": { "tags": [ "System" ], "operationId": "bot", "summary": "ZahifBot crawler information page", "description": "صفحة معلومات عليم زاحف الويب بوت", "security": [], "responses": { "200": { "description": "Text page", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/v2/scrape": { "post": { "tags": [ "Scrape" ], "operationId": "scrape", "summary": "Scrape one URL into Markdown, HTML, JSON, screenshot and more", "description": "جلب صفحة واحدة وتحويلها إلى Markdown أو JSON أو لقطة شاشة وغيرها", "x-summary-ar": "جلب صفحة واحدة وتحويلها إلى Markdown أو JSON أو لقطة شاشة وغيرها", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeRequest" }, "example": { "url": "https://ar.wikipedia.org/wiki/الرياض", "formats": [ "markdown", "links" ], "onlyMainContent": true, "mode": "fast" } } } }, "responses": { "200": { "description": "Scraped document", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Document" } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "markdown": "# الرياض\n\nالرياض عاصمة المملكة العربية السعودية…", "metadata": { "title": "الرياض - ويكيبيديا", "language": "ar", "sourceURL": "https://ar.wikipedia.org/wiki/الرياض", "statusCode": 200, "creditsUsed": 1, "engine": "fetch", "quality": 0.91, "cacheState": "miss" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/batch/scrape": { "post": { "tags": [ "Batch" ], "operationId": "batchScrape", "summary": "Start a batch scrape of many URLs", "description": "بدء جلب دفعة روابط", "x-summary-ar": "بدء جلب دفعة روابط", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchScrapeRequest" }, "example": { "urls": [ "https://example.com", "https://example.org" ], "formats": [ "markdown" ] } } } }, "responses": { "200": { "description": "Batch accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "url": { "type": "string" }, "invalidURLs": { "type": "array", "items": { "type": "string" } } }, "required": [ "success", "id" ] }, "example": { "success": true, "id": "0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0", "url": "https://web-crawler.aleem-ai.com/v2/batch/scrape/0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0", "invalidURLs": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/batch/scrape/{id}": { "get": { "tags": [ "Batch" ], "operationId": "batchScrapeStatus", "summary": "Batch status and results", "description": "حالة الدفعة ونتائجها", "x-summary-ar": "حالة الدفعة ونتائجها", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id" }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Results to skip (paging)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Max results in this page" } ], "responses": { "200": { "description": "Batch job status, progress and results (paged with next)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobView" }, "example": { "success": true, "status": "scraping", "total": 25, "completed": 9, "creditsUsed": 9, "expiresAt": "2026-11-04T19:00:00.000Z", "next": null, "progress": { "phase": "scrape", "pct": 36, "message_ar": "تُجلب الصفحات", "message_en": "Scraping pages" }, "data": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Batch" ], "operationId": "batchScrapeCancel", "summary": "Cancel a batch", "description": "إلغاء الدفعة", "x-summary-ar": "إلغاء الدفعة", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id" } ], "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string", "enum": [ "cancelled" ] } } }, "example": { "success": true, "status": "cancelled" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/batch/scrape/{id}/errors": { "get": { "tags": [ "Batch" ], "operationId": "batchScrapeErrors", "summary": "Batch errors", "description": "أخطاء الدفعة", "x-summary-ar": "أخطاء الدفعة", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id" } ], "responses": { "200": { "description": "Per-URL errors and robots-blocked URLs", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "timestamp": { "type": "string" }, "url": { "type": "string" }, "error": { "type": "string" } } } }, "robotsBlocked": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/crawl": { "post": { "tags": [ "Crawl" ], "operationId": "crawl", "summary": "Start a crawl of a website", "description": "بدء زحف موقع", "x-summary-ar": "بدء زحف موقع", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlRequest" }, "example": { "url": "https://example.com", "limit": 25, "maxDiscoveryDepth": 2, "scrapeOptions": { "formats": [ "markdown" ] }, "webhook": { "url": "https://hooks.example.com/zahif", "events": [ "completed", "failed" ] }, "mode": "extended" } } } }, "responses": { "200": { "description": "Job accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string", "description": "Job id" }, "url": { "type": "string", "description": "Status URL" } }, "required": [ "success", "id" ] }, "example": { "success": true, "id": "0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0", "url": "https://web-crawler.aleem-ai.com/v2/crawl/0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/crawl/{id}": { "get": { "tags": [ "Crawl" ], "operationId": "crawlStatus", "summary": "Crawl status and results", "description": "حالة الزحف ونتائجه", "x-summary-ar": "حالة الزحف ونتائجه", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id" }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Results to skip (paging)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Max results in this page" } ], "responses": { "200": { "description": "Crawl job status, progress and results (paged with next)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobView" }, "example": { "success": true, "status": "scraping", "total": 25, "completed": 9, "creditsUsed": 9, "expiresAt": "2026-11-04T19:00:00.000Z", "next": null, "progress": { "phase": "scrape", "pct": 36, "message_ar": "تُجلب الصفحات", "message_en": "Scraping pages" }, "data": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Crawl" ], "operationId": "crawlCancel", "summary": "Cancel a crawl", "description": "إلغاء الزحف", "x-summary-ar": "إلغاء الزحف", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id" } ], "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string", "enum": [ "cancelled" ] } } }, "example": { "success": true, "status": "cancelled" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/crawl/{id}/errors": { "get": { "tags": [ "Crawl" ], "operationId": "crawlErrors", "summary": "Crawl errors", "description": "أخطاء الزحف", "x-summary-ar": "أخطاء الزحف", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id" } ], "responses": { "200": { "description": "Per-URL errors and robots-blocked URLs", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "timestamp": { "type": "string" }, "url": { "type": "string" }, "error": { "type": "string" } } } }, "robotsBlocked": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/crawl/active": { "get": { "tags": [ "Crawl" ], "operationId": "crawlActive", "summary": "Active crawls of this team", "description": "عمليات الزحف النشطة", "x-summary-ar": "عمليات الزحف النشطة", "responses": { "200": { "description": "Active crawls", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "crawls": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "url": { "type": "string" }, "options": { "type": "object" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/crawl/params-preview": { "post": { "tags": [ "Crawl" ], "operationId": "crawlParamsPreview", "summary": "Turn a natural-language prompt into crawl parameters (no crawl is started)", "description": "تحويل وصف نصي إلى معاملات زحف دون بدء الزحف", "x-summary-ar": "تحويل وصف نصي إلى معاملات زحف دون بدء الزحف", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "prompt": { "type": "string" } }, "required": [ "url", "prompt" ] }, "example": { "url": "https://example.com", "prompt": "only blog posts from 2026" } } } }, "responses": { "200": { "description": "Suggested parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/CrawlRequest" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/map": { "post": { "tags": [ "Map" ], "operationId": "map", "summary": "Discover the URLs of a site (sitemaps + links), optionally ranked by a search term", "description": "اكتشاف روابط الموقع مع ترتيبها بكلمة بحث اختيارياً", "x-summary-ar": "اكتشاف روابط الموقع مع ترتيبها بكلمة بحث اختيارياً", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapRequest" }, "example": { "url": "https://example.com", "search": "pricing", "limit": 100 } } } }, "responses": { "200": { "description": "Links", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/MapLink" } } }, "required": [ "success", "links" ] }, "example": { "success": true, "links": [ { "url": "https://example.com/pricing", "title": "Pricing" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/search": { "post": { "tags": [ "Search" ], "operationId": "search", "summary": "Web, news and image search fused from several free sources; optionally scrape the hits", "description": "بحث في الويب والأخبار والصور بدمج مصادر مجانية متعددة مع جلب النتائج اختيارياً", "x-summary-ar": "بحث في الويب والأخبار والصور بدمج مصادر مجانية متعددة مع جلب النتائج اختيارياً", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" }, "example": { "query": "عجز الميزانية السعودية 2026", "limit": 5, "sources": [ "web", "news" ], "mode": "extended" } } } }, "responses": { "200": { "description": "Results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/SearchData" }, "creditsUsed": { "type": "number" } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "web": [ { "url": "https://example.com/a", "title": "…", "description": "…", "position": 1, "source": "bing+ddg" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/extract": { "post": { "tags": [ "Extract" ], "operationId": "extract", "summary": "Start structured extraction from URLs (and optionally the web) with a schema or prompt", "description": "بدء استخراج بيانات منظمة من روابط أو من الويب بمخطط أو تعليمات", "x-summary-ar": "بدء استخراج بيانات منظمة من روابط أو من الويب بمخطط أو تعليمات", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractRequest" }, "example": { "urls": [ "https://example.com/*" ], "prompt": "Company name and pricing plans", "schema": { "type": "object", "properties": { "company": { "type": "string" }, "plans": { "type": "array", "items": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "Job accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string", "description": "Job id" }, "url": { "type": "string", "description": "Status URL" } }, "required": [ "success", "id" ] }, "example": { "success": true, "id": "0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0", "url": "https://web-crawler.aleem-ai.com/v2/extract/0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/extract/{id}": { "get": { "tags": [ "Extract" ], "operationId": "extractStatus", "summary": "Extraction status and result", "description": "حالة الاستخراج ونتيجته", "x-summary-ar": "حالة الاستخراج ونتيجته", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id" } ], "responses": { "200": { "description": "Extract job status, progress and results (paged with next)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobView" }, "example": { "success": true, "status": "scraping", "total": 25, "completed": 9, "creditsUsed": 9, "expiresAt": "2026-11-04T19:00:00.000Z", "next": null, "progress": { "phase": "scrape", "pct": 36, "message_ar": "تُجلب الصفحات", "message_en": "Scraping pages" }, "data": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/agent": { "post": { "tags": [ "Research" ], "operationId": "agent", "summary": "Start the research agent: plan, search, read, rank and answer with numbered citations", "description": "بدء وكيل البحث: يخطط ويبحث ويقرأ ويرتب ويجيب باقتباسات مرقّمة", "x-summary-ar": "بدء وكيل البحث: يخطط ويبحث ويقرأ ويرتب ويجيب باقتباسات مرقّمة", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRequest" }, "example": { "prompt": "What were Saudi Arabia's 2025 budget deficit figures? Cite sources.", "mode": "extended", "maxCredits": 200 } } } }, "responses": { "200": { "description": "Job accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string", "description": "Job id" }, "url": { "type": "string", "description": "Status URL" } }, "required": [ "success", "id" ] }, "example": { "success": true, "id": "0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0", "url": "https://web-crawler.aleem-ai.com/v2/agent/0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/agent/{id}": { "get": { "tags": [ "Research" ], "operationId": "agentStatus", "summary": "Research status, answer and sources", "description": "حالة البحث وإجابته ومصادره", "x-summary-ar": "حالة البحث وإجابته ومصادره", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id" } ], "responses": { "200": { "description": "Agent job status, progress and results (paged with next)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobView" }, "example": { "success": true, "status": "scraping", "total": 25, "completed": 9, "creditsUsed": 9, "expiresAt": "2026-11-04T19:00:00.000Z", "next": null, "progress": { "phase": "scrape", "pct": 36, "message_ar": "تُجلب الصفحات", "message_en": "Scraping pages" }, "data": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Research" ], "operationId": "agentCancel", "summary": "Cancel research", "description": "إلغاء البحث", "x-summary-ar": "إلغاء البحث", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id" } ], "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string", "enum": [ "cancelled" ] } } }, "example": { "success": true, "status": "cancelled" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/research/{id}": { "get": { "tags": [ "Research" ], "operationId": "zahifResearchStatus", "summary": "Alias of GET /v2/agent/{id}", "description": "اسم بديل لـ GET /v2/agent/{id}", "x-summary-ar": "اسم بديل لـ GET /v2/agent/{id}", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id" } ], "responses": { "200": { "description": "Agent job status, progress and results (paged with next)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobView" }, "example": { "success": true, "status": "scraping", "total": 25, "completed": 9, "creditsUsed": 9, "expiresAt": "2026-11-04T19:00:00.000Z", "next": null, "progress": { "phase": "scrape", "pct": 36, "message_ar": "تُجلب الصفحات", "message_en": "Scraping pages" }, "data": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Research" ], "operationId": "zahifResearchCancel", "summary": "Alias of DELETE /v2/agent/{id}", "description": "اسم بديل لـ DELETE /v2/agent/{id}", "x-summary-ar": "اسم بديل لـ DELETE /v2/agent/{id}", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id" } ], "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string", "enum": [ "cancelled" ] } } }, "example": { "success": true, "status": "cancelled" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/research": { "post": { "tags": [ "Research" ], "operationId": "zahifResearch", "summary": "Alias of POST /v2/agent", "description": "اسم بديل لـ POST /v2/agent", "x-summary-ar": "اسم بديل لـ POST /v2/agent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRequest" }, "example": { "prompt": "ما أحدث أرقام عجز الميزانية السعودية؟ اذكر المصادر.", "mode": "deep" } } } }, "responses": { "200": { "description": "Job accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string", "description": "Job id" }, "url": { "type": "string", "description": "Status URL" } }, "required": [ "success", "id" ] }, "example": { "success": true, "id": "0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0", "url": "https://web-crawler.aleem-ai.com/v2/agent/0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/team/credit-usage": { "get": { "tags": [ "Account" ], "operationId": "creditUsage", "summary": "Remaining credits and plan usage", "description": "الرصيد المتبقي واستهلاك الخطة", "x-summary-ar": "الرصيد المتبقي واستهلاك الخطة", "responses": { "200": { "description": "Usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Usage" } } }, "example": { "success": true, "data": { "remainingCredits": 99120, "planCredits": 100000 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/team/token-usage": { "get": { "tags": [ "Account" ], "operationId": "tokenUsage", "summary": "LLM token usage", "description": "استهلاك رموز النماذج اللغوية", "x-summary-ar": "استهلاك رموز النماذج اللغوية", "responses": { "200": { "description": "Token usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "remainingTokens": { "type": "number" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/team/queue-status": { "get": { "tags": [ "Account" ], "operationId": "queueStatus", "summary": "Queue status for this team", "description": "حالة الطابور", "x-summary-ar": "حالة الطابور", "responses": { "200": { "description": "Queue", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "jobsInQueue": { "type": "integer" }, "activeJobsInQueue": { "type": "integer" }, "waitingJobsInQueue": { "type": "integer" }, "maxConcurrency": { "type": "integer" }, "mostRecentSuccess": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/settings": { "get": { "tags": [ "Settings" ], "operationId": "getSettings", "summary": "The settings profile of this key", "description": "ملف إعدادات المفتاح", "x-summary-ar": "ملف إعدادات المفتاح", "responses": { "200": { "description": "Profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "mode": { "$ref": "#/components/schemas/Mode" }, "profile": { "type": "object", "additionalProperties": true }, "effective": { "type": "object", "additionalProperties": true, "description": "Merged: mode defaults < profile" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "tags": [ "Settings" ], "operationId": "putSettings", "summary": "Save the settings profile of this key (validated against the registry)", "description": "حفظ ملف إعدادات المفتاح بعد التحقق من السجل", "x-summary-ar": "حفظ ملف إعدادات المفتاح بعد التحقق من السجل", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "additionalProperties": true }, "mode": { "$ref": "#/components/schemas/Mode" } }, "required": [ "settings" ] }, "example": { "settings": { "respect_robots": true, "search.max_sources": 12 } } } } }, "responses": { "200": { "description": "Saved (400 with details {unknown, invalid} when a key or value is rejected)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "mode": { "$ref": "#/components/schemas/Mode" }, "profile": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/settings/schema": { "get": { "tags": [ "Settings" ], "operationId": "settingsSchema", "summary": "Settings registry: every switch with type, defaults per mode and Arabic/English labels", "description": "سجل الإعدادات: كل مفتاح بنوعه وقيمه الافتراضية لكل وضع وتسمياته", "responses": { "200": { "description": "Schema", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string" }, "modes": { "type": "object" }, "settings": { "type": "array", "items": { "$ref": "#/components/schemas/SettingSpec" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/keys": { "get": { "tags": [ "Admin" ], "operationId": "listKeys", "summary": "List API keys (admin)", "description": "عرض المفاتيح (للمشرف)", "x-summary-ar": "عرض المفاتيح (للمشرف)", "responses": { "200": { "description": "Keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "keys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "prefix": { "type": "string" }, "name": { "type": "string" }, "team_id": { "type": "string" }, "scopes": { "type": "string" }, "plan_credits": { "type": "integer" }, "rate_per_min": { "type": "integer" }, "created_at": { "type": "string" }, "last_used_at": { "type": "string" }, "revoked_at": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Admin" ], "operationId": "createKey", "summary": "Create an API key (admin). The key is returned once.", "description": "إنشاء مفتاح (للمشرف)؛ يظهر مرة واحدة", "x-summary-ar": "إنشاء مفتاح (للمشرف)؛ يظهر مرة واحدة", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "teamId": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "api", "mcp", "admin" ] } }, "planCredits": { "type": "integer" }, "ratePerMin": { "type": "integer" } } }, "example": { "name": "aleem", "scopes": [ "api", "mcp" ], "planCredits": 100000 } } } }, "responses": { "200": { "description": "Created (HTTP 201). planCredits defaults to 500 (trial key).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "key": { "type": "string", "description": "zh- + 40 random characters" }, "prefix": { "type": "string" }, "note": { "type": "string" } } }, "example": { "success": true, "id": "k_…", "key": "zh-…", "prefix": "zh-ab12", "note": "Store this key now; it is shown only once." } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/keys/{id}": { "delete": { "tags": [ "Admin" ], "operationId": "deleteKey", "summary": "Revoke an API key (admin)", "description": "إلغاء مفتاح (للمشرف)", "x-summary-ar": "إلغاء مفتاح (للمشرف)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Key id" } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "revoked": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/usage": { "get": { "tags": [ "Account" ], "operationId": "zahifUsage", "summary": "Usage this month by operation (admins also see budgets)", "description": "الاستهلاك هذا الشهر حسب العملية", "x-summary-ar": "الاستهلاك هذا الشهر حسب العملية", "responses": { "200": { "description": "Usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "remainingCredits": { "type": "number" }, "planCredits": { "type": "number" }, "usedCredits": { "type": "number" }, "since": { "type": "string" }, "byOperation": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string" }, "credits": { "type": "number" }, "calls": { "type": "integer" } } } }, "budgets": { "type": "object" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/capabilities": { "get": { "tags": [ "System" ], "operationId": "capabilities", "summary": "Runtime capabilities (also in GET /health): edge engines and budgets, origin engines, LLM providers, search backends, features", "description": "القدرات المتاحة فعلاً الآن", "x-summary-ar": "القدرات المتاحة فعلاً الآن", "responses": { "200": { "description": "Capabilities", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "capabilities": { "type": "object", "properties": { "edge": { "type": "object", "description": "fetch, browser (remainingMinutes), workersAi (remainingNeuronsToday), documents" }, "origin": { "type": "object", "description": "{configured, healthy, engines: {rust, go, python_browser, stealth, docling, ocr, searxng}}" }, "llm": { "type": "object" }, "search": { "type": "object" }, "features": { "type": "object", "description": "scrape, crawl, map, search, batch, extract, agent = true; parse, monitor, interact = false" }, "checkedAt": { "type": "string" } } } } }, "example": { "success": true, "capabilities": { "edge": { "fetch": { "available": true }, "browser": { "available": true, "remainingMinutes": 512.4, "monthlyMinutes": 540 } }, "origin": { "configured": false, "healthy": false, "engines": { "rust": { "available": false, "reason_en": "origin not configured", "reason_ar": "الأصل غير مُعدّ" } } }, "features": { "scrape": true, "parse": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/concurrency-check": { "get": { "tags": [ "Account" ], "operationId": "concurrencyCheck", "summary": "Active jobs of this key against the concurrency limit", "description": "المهام النشطة مقابل حد التزامن", "x-summary-ar": "المهام النشطة مقابل حد التزامن", "responses": { "200": { "description": "Concurrency", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "concurrency": { "type": "integer" }, "maxConcurrency": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/settings/owner": { "get": { "tags": [ "Admin" ], "operationId": "getOwnerSettings", "summary": "Deployment-wide owner settings (budgets, caps, safety switches)", "description": "إعدادات المالك على مستوى النشر", "x-summary-ar": "إعدادات المالك على مستوى النشر", "responses": { "200": { "description": "Owner settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "owner": { "type": "object" }, "keys": { "type": "array", "items": { "type": "string" } }, "gates": {} } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "tags": [ "Admin" ], "operationId": "putOwnerSettings", "summary": "Save owner settings (admin only)", "description": "حفظ إعدادات المالك (للمشرف)", "x-summary-ar": "حفظ إعدادات المالك (للمشرف)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "additionalProperties": true } }, "required": [ "settings" ] }, "example": { "settings": { "browser.monthly_minutes": 540, "llm.monthly_usd_cap": 50 } } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "owner": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/keys/{id}/policy": { "get": { "tags": [ "Admin" ], "operationId": "getKeyPolicy", "summary": "Per-key policy set by the admin (e.g. raised limits)", "description": "سياسة المفتاح التي يضبطها المشرف", "x-summary-ar": "سياسة المفتاح التي يضبطها المشرف", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Key id" } ], "responses": { "200": { "description": "Policy", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "policy": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "tags": [ "Admin" ], "operationId": "putKeyPolicy", "summary": "Set a key's policy (admin only)", "description": "ضبط سياسة مفتاح (للمشرف)", "x-summary-ar": "ضبط سياسة مفتاح (للمشرف)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Key id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "additionalProperties": true } }, "required": [ "settings" ] }, "example": { "settings": { "limits.max_pages": 500 } } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "policy": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/bench/score": { "post": { "tags": [ "Admin" ], "operationId": "benchScore", "summary": "Benchmark scoring on the edge: metrics only per row, never page text (admin)", "description": "قياس الأداء على الحافة: مقاييس فقط دون نص الصفحات (للمشرف)", "x-summary-ar": "قياس الأداء على الحافة: مقاييس فقط دون نص الصفحات (للمشرف)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "truth_text": { "type": "string" }, "lie_text": { "type": "string" } }, "required": [ "id", "url" ] }, "description": "At most 25 rows" }, "mode": { "$ref": "#/components/schemas/Mode" }, "options": { "type": "object", "description": "useCache and scrape options" } }, "required": [ "rows" ] }, "example": { "rows": [ { "id": "r1", "url": "https://example.com", "truth_text": "Example Domain" } ], "mode": "fast" } } } }, "responses": { "200": { "description": "Metrics per row", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "ok": { "type": "boolean" }, "status": { "type": "integer" }, "truthFound": { "type": "boolean" }, "truthTokenRecall": { "type": "number" }, "lieFound": { "type": "boolean" }, "chars": { "type": "integer" }, "tokensEst": { "type": "integer" }, "latencyMs": { "type": "integer" }, "engine": { "type": "string" }, "quality": { "type": "number" }, "cacheState": { "type": "string" }, "error": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/bench/answer": { "post": { "tags": [ "Admin" ], "operationId": "benchAnswer", "summary": "Research-correctness evaluation: answers with citations (admin)", "description": "تقييم صحة البحث: إجابات مع مصادر (للمشرف)", "x-summary-ar": "تقييم صحة البحث: إجابات مع مصادر (للمشرف)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" } }, "required": [ "id", "question" ] }, "description": "At most 10" }, "mode": { "$ref": "#/components/schemas/Mode" } }, "required": [ "questions" ] }, "example": { "questions": [ { "id": "q1", "question": "What is the capital of Saudi Arabia?" } ], "mode": "fast" } } } }, "responses": { "200": { "description": "Answers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "answer": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "latencyMs": { "type": "integer" }, "credits": { "type": "number" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/me": { "get": { "tags": [ "Account" ], "operationId": "me", "summary": "The calling key: id, name, scopes, remaining credits, last 24 h credits", "description": "المفتاح المستدعي ورصيده", "x-summary-ar": "المفتاح المستدعي ورصيده", "responses": { "200": { "description": "Key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "keyId": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "remainingCredits": { "type": "number" }, "last24hCredits": { "type": "number" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/webhook-secret": { "get": { "tags": [ "Account" ], "operationId": "webhookSecret", "summary": "The HMAC secret that signs this key's webhooks", "description": "سرّ توقيع الـ webhooks لهذا المفتاح", "x-summary-ar": "سرّ توقيع الـ webhooks لهذا المفتاح", "responses": { "200": { "description": "Secret", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "secret": { "type": "string" }, "headers": { "type": "array", "items": { "type": "string" } }, "algorithm": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/files/{key}": { "get": { "tags": [ "Account" ], "operationId": "zahifFile", "summary": "Stored screenshot or PDF produced by a scrape (unguessable name, no auth)", "description": "ملف لقطة شاشة أو PDF ناتج عن عملية جلب", "x-summary-ar": "ملف لقطة شاشة أو PDF ناتج عن عملية جلب", "security": [], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": ".png|jpg|pdf" } ], "responses": { "200": { "description": "File", "content": { "image/png": {}, "image/jpeg": {}, "application/pdf": {} } }, "404": { "description": "Not found" } } } }, "/v2/zahif/selftest": { "get": { "tags": [ "Admin" ], "operationId": "selftest", "summary": "Live self-test from the edge (admin)", "description": "اختبار ذاتي حي من الحافة (للمشرف)", "x-summary-ar": "اختبار ذاتي حي من الحافة (للمشرف)", "responses": { "200": { "description": "Results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "pass": { "type": "boolean" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "pass": { "type": "boolean" }, "ms": { "type": "integer" }, "error": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/browser/sessions": { "post": { "tags": [ "Browser" ], "operationId": "browserCreate", "summary": "Create an agent-browser session (placement, display, presence, control)", "description": "إنشاء جلسة متصفح للوكيل بمفاتيحها الأربعة", "x-summary-ar": "إنشاء جلسة متصفح للوكيل بمفاتيحها الأربعة", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserSessionRequest" }, "example": { "placement": "auto", "display": "virtual", "presence": "natural", "control": "supervised", "startUrl": "https://example.com", "timeoutSec": 600 } } } }, "responses": { "200": { "description": "Session", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "session": { "$ref": "#/components/schemas/BrowserSession" } }, "required": [ "success", "session" ] }, "example": { "success": true, "session": { "id": "bs_7f3a", "placement": "serverless_edge", "display": "virtual", "presence": "natural", "control": "supervised", "status": "ready", "url": "https://ar.wikipedia.org/wiki/الرياض", "liveViewUrl": "https://web-crawler.aleem-ai.com/app/browser/bs_7f3a", "creditsUsed": 2 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "tags": [ "Browser" ], "operationId": "browserList", "summary": "List browser sessions", "description": "عرض جلسات المتصفح", "x-summary-ar": "عرض جلسات المتصفح", "responses": { "200": { "description": "Sessions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/BrowserSession" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/browser/sessions/{id}": { "get": { "tags": [ "Browser" ], "operationId": "browserGet", "summary": "Get a browser session", "description": "حالة جلسة متصفح", "x-summary-ar": "حالة جلسة متصفح", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Browser session id" } ], "responses": { "200": { "description": "Session", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "session": { "$ref": "#/components/schemas/BrowserSession" } }, "required": [ "success", "session" ] }, "example": { "success": true, "session": { "id": "bs_7f3a", "placement": "serverless_edge", "display": "virtual", "presence": "natural", "control": "supervised", "status": "ready", "url": "https://ar.wikipedia.org/wiki/الرياض", "liveViewUrl": "https://web-crawler.aleem-ai.com/app/browser/bs_7f3a", "creditsUsed": 2 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Browser" ], "operationId": "browserClose", "summary": "Close a browser session", "description": "إغلاق جلسة المتصفح", "x-summary-ar": "إغلاق جلسة المتصفح", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Browser session id" } ], "responses": { "200": { "description": "Closed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string", "enum": [ "closed" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/browser/sessions/{id}/actions": { "post": { "tags": [ "Browser" ], "operationId": "browserAct", "summary": "Run browser actions and optionally return a snapshot", "description": "تنفيذ إجراءات في المتصفح مع لقطة اختيارية", "x-summary-ar": "تنفيذ إجراءات في المتصفح مع لقطة اختيارية", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Browser session id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "actions": { "type": "array", "items": { "$ref": "#/components/schemas/BrowserAction" } }, "action": { "$ref": "#/components/schemas/BrowserAction" }, "snapshot": { "type": "string", "enum": [ "aria", "markdown", "som", "html", "none" ], "default": "none" }, "maxChars": { "type": "integer" } } }, "example": { "actions": [ { "type": "navigate", "url": "https://example.com" }, { "type": "click", "ref": "e12" }, { "type": "type", "ref": "e7", "text": "عليم زاحف الويب" }, { "type": "press", "key": "Enter" } ], "snapshot": "aria" } } } }, "responses": { "200": { "description": "Results. A risky step under supervised control stops with error approval_required and data.approvalId; approve it with POST /sessions/{id}/approve.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BrowserActionResult" } }, "snapshot": { "$ref": "#/components/schemas/BrowserSnapshot" }, "session": { "$ref": "#/components/schemas/BrowserSession" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/browser/sessions/{id}/snapshot": { "get": { "tags": [ "Browser" ], "operationId": "browserSnapshot", "summary": "Page snapshot for agents (aria refs, markdown, set-of-marks, html)", "description": "لقطة الصفحة للوكيل", "x-summary-ar": "لقطة الصفحة للوكيل", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Browser session id" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "aria", "markdown", "som", "html" ], "default": "aria" } }, { "name": "maxChars", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Snapshot", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "snapshot": { "$ref": "#/components/schemas/BrowserSnapshot" } } }, "example": { "success": true, "snapshot": { "url": "https://example.com", "format": "aria", "content": "- heading \"Example Domain\" [ref=e1]\n- link \"More information...\" [ref=e2]", "refs": 2 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/browser/sessions/{id}/screenshot": { "get": { "tags": [ "Browser" ], "operationId": "browserScreenshot", "summary": "Screenshot: raw image bytes by default, JSON {image (base64), mime} with as=json", "description": "لقطة شاشة: صورة خام افتراضياً أو JSON مع as=json", "x-summary-ar": "لقطة شاشة: صورة خام افتراضياً أو JSON مع as=json", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Browser session id" }, { "name": "fullPage", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "marks", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Set-of-marks boxes over interactive elements" }, { "name": "as", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json" ] }, "description": "Return JSON instead of image bytes" } ], "responses": { "200": { "description": "image/png or image/jpeg bytes; with as=json: {success, image, mime}", "content": { "image/png": { "schema": { "type": "string", "contentMediaType": "image/png" } }, "image/jpeg": { "schema": { "type": "string", "contentMediaType": "image/jpeg" } }, "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "image": { "type": "string", "description": "base64" }, "mime": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/browser/sessions/{id}/live": { "get": { "tags": [ "Browser" ], "operationId": "browserLive", "summary": "Live view stream: Server-Sent Events of JPEG frames and session events", "description": "بث العرض الحي: أحداث SSE بإطارات JPEG وأحداث الجلسة", "x-summary-ar": "بث العرض الحي: أحداث SSE بإطارات JPEG وأحداث الجلسة", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Browser session id" } ], "responses": { "200": { "description": "Server-Sent Events. event: session (full view on connect) | status {status,url,title} | frame {mime, data (base64)} | navigated {url,title} | console | approval {id, reason, action} | approval_decided {id, approved} | handoff {reason} | resumed | paused | device_offline | closed {creditsUsed} | ping", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/browser/sessions/{id}/handoff": { "post": { "tags": [ "Browser" ], "operationId": "browserHandoff", "summary": "Pause the agent and hand control to a human", "description": "إيقاف الوكيل وتسليم التحكم للإنسان", "x-summary-ar": "إيقاف الوكيل وتسليم التحكم للإنسان", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Browser session id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } }, "example": { "reason": "login with 2FA" } } } }, "responses": { "200": { "description": "Session in handoff", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "session": { "$ref": "#/components/schemas/BrowserSession" } }, "required": [ "success", "session" ] }, "example": { "success": true, "session": { "id": "bs_7f3a", "placement": "serverless_edge", "display": "virtual", "presence": "natural", "control": "supervised", "status": "ready", "url": "https://ar.wikipedia.org/wiki/الرياض", "liveViewUrl": "https://web-crawler.aleem-ai.com/app/browser/bs_7f3a", "creditsUsed": 2 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/browser/sessions/{id}/resume": { "post": { "tags": [ "Browser" ], "operationId": "browserResume", "summary": "Give control back to the agent", "description": "إعادة التحكم للوكيل", "x-summary-ar": "إعادة التحكم للوكيل", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Browser session id" } ], "responses": { "200": { "description": "Session resumed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "session": { "$ref": "#/components/schemas/BrowserSession" } }, "required": [ "success", "session" ] }, "example": { "success": true, "session": { "id": "bs_7f3a", "placement": "serverless_edge", "display": "virtual", "presence": "natural", "control": "supervised", "status": "ready", "url": "https://ar.wikipedia.org/wiki/الرياض", "liveViewUrl": "https://web-crawler.aleem-ai.com/app/browser/bs_7f3a", "creditsUsed": 2 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/browser/sessions/{id}/approve": { "post": { "tags": [ "Browser" ], "operationId": "browserApprove", "summary": "Approve or deny the pending risky step (supervised control)", "description": "الموافقة على خطوة حساسة معلّقة أو رفضها في وضع الإشراف", "x-summary-ar": "الموافقة على خطوة حساسة معلّقة أو رفضها في وضع الإشراف", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Browser session id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approvalId": { "type": "string" }, "approve": { "type": "boolean", "default": true } }, "required": [ "approvalId" ] }, "example": { "approvalId": "ap_1", "approve": true } } } }, "responses": { "200": { "description": "Decision recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "approved": { "type": "boolean" }, "result": {}, "session": { "$ref": "#/components/schemas/BrowserSession" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/browser/sessions/{id}/input": { "post": { "tags": [ "Browser" ], "operationId": "browserInput", "summary": "Human input while in handoff (from the live view)", "description": "إدخال الإنسان أثناء تولّيه التحكم", "x-summary-ar": "إدخال الإنسان أثناء تولّيه التحكم", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Browser session id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "mousemove", "mousedown", "mouseup", "click", "wheel", "keydown", "keyup", "press", "text" ] }, "x": { "type": "number" }, "y": { "type": "number" }, "button": { "type": "string", "enum": [ "left", "right", "middle" ] }, "deltaX": { "type": "number" }, "deltaY": { "type": "number" }, "key": { "type": "string" }, "text": { "type": "string" } }, "required": [ "type" ] } } }, "required": [ "events" ] }, "example": { "events": [ { "type": "click", "x": 420, "y": 310, "button": "left" }, { "type": "text", "text": "عليم زاحف الويب" }, { "type": "press", "key": "Enter" } ] } } } }, "responses": { "200": { "description": "Applied", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/browser/sessions/{id}/log": { "get": { "tags": [ "Browser" ], "operationId": "browserLog", "summary": "Audit log of the session's actions", "description": "سجل تدقيق إجراءات الجلسة", "x-summary-ar": "سجل تدقيق إجراءات الجلسة", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Browser session id" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 200 } } ], "responses": { "200": { "description": "Log", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "log": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/browser/status": { "get": { "tags": [ "Browser" ], "operationId": "browserStatus", "summary": "Available placements, switches, relay endpoint, budgets and per-minute pricing", "description": "مواضع التشغيل المتاحة والميزانيات والتسعير", "x-summary-ar": "مواضع التشغيل المتاحة والميزانيات والتسعير", "responses": { "200": { "description": "Capabilities", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "placements": { "type": "object" }, "presence": { "type": "array", "items": { "type": "string" } }, "control": { "type": "array", "items": { "type": "string" } }, "snapshot": { "type": "array", "items": { "type": "string" } }, "relay": { "type": "object" }, "budgets": {}, "pricing": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/browser/files/{sid}/{name}": { "get": { "tags": [ "Browser" ], "operationId": "browserFile", "summary": "Download a file saved by a download or pdf action (served as an attachment)", "description": "تنزيل ملف حفظته الجلسة", "x-summary-ar": "تنزيل ملف حفظته الجلسة", "parameters": [ { "name": "sid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Browser session id" }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File bytes (Content-Disposition: attachment)", "content": { "application/octet-stream": {} } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/browser/profiles/{name}": { "delete": { "tags": [ "Browser" ], "operationId": "browserProfileDelete", "summary": "Delete a stored browser profile (cookies and storage)", "description": "حذف ملف متصفح محفوظ", "x-summary-ar": "حذف ملف متصفح محفوظ", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "deleted": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/browser/devices": { "get": { "tags": [ "Devices" ], "operationId": "devicesList", "summary": "List paired devices and their online state", "description": "الأجهزة المقترنة وحالة اتصالها", "x-summary-ar": "الأجهزة المقترنة وحالة اتصالها", "responses": { "200": { "description": "Devices", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/Device" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/browser/devices/{id}": { "delete": { "tags": [ "Devices" ], "operationId": "deviceDelete", "summary": "Remove a paired device", "description": "إزالة جهاز مقترن", "x-summary-ar": "إزالة جهاز مقترن", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Device id" } ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/browser/devices/pair": { "post": { "tags": [ "Devices" ], "operationId": "devicePair", "summary": "Create an 8-character pairing code (valid 10 minutes)", "description": "إنشاء رمز اقتران من ٨ خانات صالح ١٠ دقائق", "x-summary-ar": "إنشاء رمز اقتران من ٨ خانات صالح ١٠ دقائق", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } } }, "example": { "name": "office laptop" } } } }, "responses": { "200": { "description": "Code", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "pairingCode": { "type": "string" }, "expiresAt": { "type": "string" } } }, "example": { "success": true, "pairingCode": "K7Q2-M9XD", "expiresAt": "2026-11-03T17:20:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/browser/devices/redeem": { "post": { "tags": [ "Devices" ], "operationId": "deviceRedeem", "summary": "Redeem a pairing code from the extension or zahif-relay (no API key; the code is the credential)", "description": "استبدال رمز الاقتران من الإضافة أو برنامج الترحيل", "x-summary-ar": "استبدال رمز الاقتران من الإضافة أو برنامج الترحيل", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "platform": { "type": "string" } }, "required": [ "code" ] }, "example": { "code": "K7Q2-M9XD", "name": "office laptop", "platform": "chrome-extension" } } } }, "responses": { "200": { "description": "Device credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "deviceId": { "type": "string" }, "deviceToken": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/browser/relay": { "get": { "tags": [ "Devices" ], "operationId": "deviceRelay", "summary": "WebSocket upgrade for paired devices (JSON-RPC 2.0, outbound from the device)", "description": "اتصال WebSocket للأجهزة المقترنة", "x-summary-ar": "اتصال WebSocket للأجهزة المقترنة", "security": [], "parameters": [ { "name": "token", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Device token (or Sec-WebSocket-Protocol)" } ], "responses": { "101": { "description": "Switching Protocols" }, "200": { "description": "Not a WebSocket request: relay info" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/billing": { "get": { "tags": [ "Billing" ], "operationId": "billingSummary", "summary": "Your account: status, plan, period, balance and recent ledger", "description": "حسابك: الحالة والخطة والفترة والرصيد وآخر الحركات", "x-summary-ar": "حسابك: الحالة والخطة والفترة والرصيد وآخر الحركات", "responses": { "200": { "description": "Summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "account": { "$ref": "#/components/schemas/Account" }, "plan": { "$ref": "#/components/schemas/PublicPlan" }, "recentLedger": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerEntry" } }, "notice_ar": { "type": "string" }, "notice_en": { "type": "string" }, "trial_ar": { "type": "string" }, "trial_en": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/billing/plans": { "get": { "tags": [ "Billing" ], "operationId": "billingPlans", "summary": "Public plans (no price unless approved by the owner)", "description": "الخطط المتاحة دون أسعار ما لم يعتمدها المالك", "x-summary-ar": "الخطط المتاحة دون أسعار ما لم يعتمدها المالك", "responses": { "200": { "description": "Plans", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "plans": { "type": "array", "items": { "$ref": "#/components/schemas/PublicPlan" } }, "notice_ar": { "type": "string" }, "notice_en": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/billing/price-table": { "get": { "tags": [ "Billing" ], "operationId": "billingPriceTable", "summary": "Credit rules per operation", "description": "قواعد احتساب الرصيد لكل عملية", "x-summary-ar": "قواعد احتساب الرصيد لكل عملية", "responses": { "200": { "description": "Rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "version": { "type": "string" }, "credits": { "type": "object" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "op": { "type": "string" }, "rule_ar": { "type": "string" }, "rule_en": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/billing/quote": { "post": { "tags": [ "Billing" ], "operationId": "billingQuote", "summary": "Estimate the credits of a request before running it", "description": "تقدير رصيد طلب قبل تشغيله", "x-summary-ar": "تقدير رصيد طلب قبل تشغيله", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "op": { "type": "string", "enum": [ "scrape", "crawl", "batch", "map", "search", "extract", "agent", "browser" ] }, "units": { "type": "object" }, "request": { "type": "object" } }, "required": [ "op" ] }, "example": { "op": "scrape", "request": { "url": "https://example.com", "formats": [ "markdown", "json" ] } } } } }, "responses": { "200": { "description": "Estimate", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "estimate": { "type": "object", "properties": { "op": { "type": "string" }, "credits": { "type": "number" } } }, "quote": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/billing/ledger": { "get": { "tags": [ "Billing" ], "operationId": "billingLedger", "summary": "Ledger entries of your account", "description": "حركات حسابك", "x-summary-ar": "حركات حسابك", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Ledger", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerEntry" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/billing/statement": { "get": { "tags": [ "Billing" ], "operationId": "billingStatement", "summary": "Monthly statement (Arabic HTML or JSON)", "description": "كشف الحساب الشهري", "x-summary-ar": "كشف الحساب الشهري", "parameters": [ { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "html", "json" ] } }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string" }, "description": "YYYY-MM" } ], "responses": { "200": { "description": "Statement", "content": { "text/html": {}, "application/json": {} } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/billing/alerts": { "get": { "tags": [ "Billing" ], "operationId": "billingAlertsGet", "summary": "Balance alert webhook, thresholds and signing secret", "description": "تنبيهات الرصيد وسرّ التوقيع", "x-summary-ar": "تنبيهات الرصيد وسرّ التوقيع", "responses": { "200": { "description": "Alerts", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "webhook": { "type": [ "string", "null" ] }, "thresholds": { "type": "array", "items": { "type": "number" } }, "secret": { "type": "string" }, "header": { "type": "string" }, "algorithm": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "tags": [ "Billing" ], "operationId": "billingAlertsPut", "summary": "Set or clear the balance alert webhook", "description": "ضبط رابط تنبيهات الرصيد أو مسحه", "x-summary-ar": "ضبط رابط تنبيهات الرصيد أو مسحه", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "type": [ "string", "null" ] } } }, "example": { "webhook": "https://hooks.example.com/billing" } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "webhook": { "type": [ "string", "null" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/admin/accounts": { "get": { "tags": [ "Admin" ], "operationId": "adminAccounts", "summary": "List accounts (admin)", "description": "عرض الحسابات (للمشرف)", "x-summary-ar": "عرض الحسابات (للمشرف)", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "suspended", "cancelled" ] } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Admin" ], "operationId": "adminAccountCreate", "summary": "Create an account, optionally with a key and opening credits (admin)", "description": "إنشاء حساب مع مفتاح ورصيد افتتاحي اختيارياً (للمشرف)", "x-summary-ar": "إنشاء حساب مع مفتاح ورصيد افتتاحي اختيارياً (للمشرف)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "planId": { "type": "string" }, "cycle": { "type": "string", "enum": [ "monthly", "yearly" ] }, "creditsOverride": { "type": [ "number", "null" ] }, "limitsOverride": { "type": "object" }, "alertWebhook": { "type": "string" }, "notes": { "type": "string" }, "anchor": { "type": "string" }, "issueKey": { "oneOf": [ { "type": "boolean" }, { "type": "object", "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } } } ] }, "packCredits": { "type": "integer" } }, "required": [ "name" ] }, "example": { "name": "Aleem", "planId": "free", "issueKey": true } } } }, "responses": { "200": { "description": "Created (HTTP 201)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "account": { "$ref": "#/components/schemas/Account" }, "key": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/admin/accounts/{id}": { "get": { "tags": [ "Admin" ], "operationId": "adminAccount", "summary": "Account detail with its keys (admin)", "description": "تفاصيل الحساب ومفاتيحه (للمشرف)", "x-summary-ar": "تفاصيل الحساب ومفاتيحه (للمشرف)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Account id" } ], "responses": { "200": { "description": "Account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "account": { "$ref": "#/components/schemas/Account" }, "keys": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "tags": [ "Admin" ], "operationId": "adminAccountPatch", "summary": "Update account fields (admin)", "description": "تعديل بيانات الحساب (للمشرف)", "x-summary-ar": "تعديل بيانات الحساب (للمشرف)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "account": { "$ref": "#/components/schemas/Account" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Admin" ], "operationId": "adminAccountPatchPost", "summary": "POST alias of PATCH for clients without PATCH (admin)", "description": "اسم بديل لـ PATCH (للمشرف)", "x-summary-ar": "اسم بديل لـ PATCH (للمشرف)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "account": { "$ref": "#/components/schemas/Account" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/admin/accounts/{id}/suspend": { "post": { "tags": [ "Admin" ], "operationId": "adminSuspend", "summary": "Suspend an account (admin)", "description": "إيقاف حساب (للمشرف)", "x-summary-ar": "إيقاف حساب (للمشرف)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } }, "example": { "reason": "requested by the customer" } } } }, "responses": { "200": { "description": "Account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "account": { "$ref": "#/components/schemas/Account" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/admin/accounts/{id}/resume": { "post": { "tags": [ "Admin" ], "operationId": "adminResume", "summary": "Resume an account (admin)", "description": "إعادة تفعيل حساب (للمشرف)", "x-summary-ar": "إعادة تفعيل حساب (للمشرف)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } }, "example": { "reason": "requested by the customer" } } } }, "responses": { "200": { "description": "Account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "account": { "$ref": "#/components/schemas/Account" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/admin/accounts/{id}/cancel": { "post": { "tags": [ "Admin" ], "operationId": "adminCancel", "summary": "Cancel an account (admin)", "description": "إلغاء حساب (للمشرف)", "x-summary-ar": "إلغاء حساب (للمشرف)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } }, "example": { "reason": "requested by the customer" } } } }, "responses": { "200": { "description": "Account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "account": { "$ref": "#/components/schemas/Account" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/admin/accounts/{id}/plan": { "post": { "tags": [ "Admin" ], "operationId": "adminPlan", "summary": "Change plan and cycle (admin); no proration", "description": "تغيير الخطة والدورة (للمشرف) دون احتساب تناسبي", "x-summary-ar": "تغيير الخطة والدورة (للمشرف) دون احتساب تناسبي", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "planId": { "type": "string" }, "cycle": { "type": "string", "enum": [ "monthly", "yearly" ] }, "resetPeriod": { "type": "boolean" }, "creditsOverride": { "type": [ "number", "null" ] } }, "required": [ "planId" ] }, "example": { "planId": "free", "cycle": "monthly" } } } }, "responses": { "200": { "description": "Plan changed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "account": { "$ref": "#/components/schemas/Account" }, "note_ar": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/admin/accounts/{id}/credits": { "post": { "tags": [ "Admin" ], "operationId": "adminCredits", "summary": "Add credits: pack, grant or adjustment (admin)", "description": "إضافة رصيد: حزمة أو منحة أو تعديل (للمشرف)", "x-summary-ar": "إضافة رصيد: حزمة أو منحة أو تعديل (للمشرف)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "pack", "grant", "adjust" ] }, "packs": { "type": "integer" }, "credits": { "type": "integer" }, "reason": { "type": "string" } }, "required": [ "kind" ] }, "example": { "kind": "grant", "credits": 500, "reason": "trial" } } } }, "responses": { "200": { "description": "Added", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "added": { "type": "number" }, "kind": { "type": "string" }, "balance": { "$ref": "#/components/schemas/Balance" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/admin/accounts/{id}/keys": { "get": { "tags": [ "Admin" ], "operationId": "adminAccountKeys", "summary": "Keys of an account (admin)", "description": "مفاتيح الحساب (للمشرف)", "x-summary-ar": "مفاتيح الحساب (للمشرف)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Account id" } ], "responses": { "200": { "description": "Keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "keys": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Admin" ], "operationId": "adminAccountKeyCreate", "summary": "Issue a key for an account (admin); shown once", "description": "إصدار مفتاح للحساب (للمشرف)؛ يظهر مرة واحدة", "x-summary-ar": "إصدار مفتاح للحساب (للمشرف)؛ يظهر مرة واحدة", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "example": { "name": "aleem worker" } } } }, "responses": { "200": { "description": "Created (HTTP 201)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "key": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/admin/accounts/{id}/keys/{keyId}": { "delete": { "tags": [ "Admin" ], "operationId": "adminAccountKeyRevoke", "summary": "Revoke a key of an account (admin)", "description": "إلغاء مفتاح من الحساب (للمشرف)", "x-summary-ar": "إلغاء مفتاح من الحساب (للمشرف)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Account id" }, { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "revoked": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/admin/accounts/{id}/usage": { "get": { "tags": [ "Admin" ], "operationId": "adminAccountUsage", "summary": "Usage of an account by operation and day (admin)", "description": "استهلاك الحساب حسب العملية واليوم (للمشرف)", "x-summary-ar": "استهلاك الحساب حسب العملية واليوم (للمشرف)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Account id" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "accountId": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "totalCredits": { "type": "number" }, "byOperation": { "type": "array", "items": { "type": "object" } }, "byDay": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/admin/accounts/{id}/ledger": { "get": { "tags": [ "Admin" ], "operationId": "adminAccountLedger", "summary": "Ledger of an account (admin)", "description": "حركات الحساب (للمشرف)", "x-summary-ar": "حركات الحساب (للمشرف)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Account id" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Ledger", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerEntry" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/admin/accounts/{id}/statement": { "get": { "tags": [ "Admin" ], "operationId": "adminAccountStatement", "summary": "Statement of an account (admin)", "description": "كشف حساب (للمشرف)", "x-summary-ar": "كشف حساب (للمشرف)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Account id" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "html", "json" ] } } ], "responses": { "200": { "description": "Statement", "content": { "text/html": {}, "application/json": {} } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/admin/plans": { "get": { "tags": [ "Admin" ], "operationId": "adminPlans", "summary": "All plans with their approval state (admin)", "description": "كل الخطط وحالة اعتمادها (للمشرف)", "x-summary-ar": "كل الخطط وحالة اعتمادها (للمشرف)", "responses": { "200": { "description": "Plans", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "plans": { "type": "array", "items": { "type": "object" } }, "notice_ar": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/admin/plans/{id}": { "put": { "tags": [ "Admin" ], "operationId": "adminPlanPut", "summary": "Edit or approve a plan's prices (owner decision)", "description": "تعديل خطة أو اعتماد أسعارها (قرار المالك)", "x-summary-ar": "تعديل خطة أو اعتماد أسعارها (قرار المالك)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plan id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "plan": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/admin/price-table": { "get": { "tags": [ "Admin" ], "operationId": "adminPriceTable", "summary": "Credit rules (admin view)", "description": "قواعد احتساب الرصيد (للمشرف)", "x-summary-ar": "قواعد احتساب الرصيد (للمشرف)", "responses": { "200": { "description": "Rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "version": { "type": "string" }, "rules": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/zahif/admin/quote": { "post": { "tags": [ "Admin" ], "operationId": "adminQuote", "summary": "Quote any operation (admin)", "description": "تسعير أي عملية بالرصيد (للمشرف)", "x-summary-ar": "تسعير أي عملية بالرصيد (للمشرف)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "op": { "type": "string" }, "units": { "type": "object" }, "request": { "type": "object" } }, "required": [ "op" ] } } } }, "responses": { "200": { "description": "Quote", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "quote": { "type": "object" }, "estimate": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/scrape": { "post": { "tags": [ "v1 aliases" ], "operationId": "scrapeV1", "summary": "v1 alias of POST /v2/scrape", "description": "جلب صفحة واحدة وتحويلها إلى Markdown أو JSON أو لقطة شاشة وغيرها", "x-summary-ar": "جلب صفحة واحدة وتحويلها إلى Markdown أو JSON أو لقطة شاشة وغيرها", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeRequest" }, "example": { "url": "https://ar.wikipedia.org/wiki/الرياض", "formats": [ "markdown", "links" ], "onlyMainContent": true, "mode": "fast" } } } }, "responses": { "200": { "description": "Scraped document", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Document" } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "markdown": "# الرياض\n\nالرياض عاصمة المملكة العربية السعودية…", "metadata": { "title": "الرياض - ويكيبيديا", "language": "ar", "sourceURL": "https://ar.wikipedia.org/wiki/الرياض", "statusCode": 200, "creditsUsed": 1, "engine": "fetch", "quality": 0.91, "cacheState": "miss" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "deprecated": true } }, "/v1/batch/scrape": { "post": { "tags": [ "v1 aliases" ], "operationId": "batchScrapeV1", "summary": "v1 alias of POST /v2/batch/scrape", "description": "بدء جلب دفعة روابط", "x-summary-ar": "بدء جلب دفعة روابط", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchScrapeRequest" }, "example": { "urls": [ "https://example.com", "https://example.org" ], "formats": [ "markdown" ] } } } }, "responses": { "200": { "description": "Batch accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "url": { "type": "string" }, "invalidURLs": { "type": "array", "items": { "type": "string" } } }, "required": [ "success", "id" ] }, "example": { "success": true, "id": "0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0", "url": "https://web-crawler.aleem-ai.com/v2/batch/scrape/0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0", "invalidURLs": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "deprecated": true } }, "/v1/batch/scrape/{id}": { "get": { "tags": [ "v1 aliases" ], "operationId": "batchScrapeStatusV1", "summary": "v1 alias of GET /v2/batch/scrape/{id}", "description": "حالة الدفعة ونتائجها", "x-summary-ar": "حالة الدفعة ونتائجها", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id" }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Results to skip (paging)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Max results in this page" } ], "responses": { "200": { "description": "Batch job status, progress and results (paged with next)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobView" }, "example": { "success": true, "status": "scraping", "total": 25, "completed": 9, "creditsUsed": 9, "expiresAt": "2026-11-04T19:00:00.000Z", "next": null, "progress": { "phase": "scrape", "pct": 36, "message_ar": "تُجلب الصفحات", "message_en": "Scraping pages" }, "data": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "deprecated": true }, "delete": { "tags": [ "v1 aliases" ], "operationId": "batchScrapeCancelV1", "summary": "v1 alias of DELETE /v2/batch/scrape/{id}", "description": "إلغاء الدفعة", "x-summary-ar": "إلغاء الدفعة", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id" } ], "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string", "enum": [ "cancelled" ] } } }, "example": { "success": true, "status": "cancelled" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "deprecated": true } }, "/v1/batch/scrape/{id}/errors": { "get": { "tags": [ "v1 aliases" ], "operationId": "batchScrapeErrorsV1", "summary": "v1 alias of GET /v2/batch/scrape/{id}/errors", "description": "أخطاء الدفعة", "x-summary-ar": "أخطاء الدفعة", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id" } ], "responses": { "200": { "description": "Per-URL errors and robots-blocked URLs", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "timestamp": { "type": "string" }, "url": { "type": "string" }, "error": { "type": "string" } } } }, "robotsBlocked": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "deprecated": true } }, "/v1/crawl": { "post": { "tags": [ "v1 aliases" ], "operationId": "crawlV1", "summary": "v1 alias of POST /v2/crawl", "description": "بدء زحف موقع", "x-summary-ar": "بدء زحف موقع", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlRequest" }, "example": { "url": "https://example.com", "limit": 25, "maxDiscoveryDepth": 2, "scrapeOptions": { "formats": [ "markdown" ] }, "webhook": { "url": "https://hooks.example.com/zahif", "events": [ "completed", "failed" ] }, "mode": "extended" } } } }, "responses": { "200": { "description": "Job accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string", "description": "Job id" }, "url": { "type": "string", "description": "Status URL" } }, "required": [ "success", "id" ] }, "example": { "success": true, "id": "0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0", "url": "https://web-crawler.aleem-ai.com/v2/crawl/0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "deprecated": true } }, "/v1/crawl/{id}": { "get": { "tags": [ "v1 aliases" ], "operationId": "crawlStatusV1", "summary": "v1 alias of GET /v2/crawl/{id}", "description": "حالة الزحف ونتائجه", "x-summary-ar": "حالة الزحف ونتائجه", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id" }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Results to skip (paging)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Max results in this page" } ], "responses": { "200": { "description": "Crawl job status, progress and results (paged with next)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobView" }, "example": { "success": true, "status": "scraping", "total": 25, "completed": 9, "creditsUsed": 9, "expiresAt": "2026-11-04T19:00:00.000Z", "next": null, "progress": { "phase": "scrape", "pct": 36, "message_ar": "تُجلب الصفحات", "message_en": "Scraping pages" }, "data": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "deprecated": true }, "delete": { "tags": [ "v1 aliases" ], "operationId": "crawlCancelV1", "summary": "v1 alias of DELETE /v2/crawl/{id}", "description": "إلغاء الزحف", "x-summary-ar": "إلغاء الزحف", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id" } ], "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string", "enum": [ "cancelled" ] } } }, "example": { "success": true, "status": "cancelled" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "deprecated": true } }, "/v1/crawl/{id}/errors": { "get": { "tags": [ "v1 aliases" ], "operationId": "crawlErrorsV1", "summary": "v1 alias of GET /v2/crawl/{id}/errors", "description": "أخطاء الزحف", "x-summary-ar": "أخطاء الزحف", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id" } ], "responses": { "200": { "description": "Per-URL errors and robots-blocked URLs", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "timestamp": { "type": "string" }, "url": { "type": "string" }, "error": { "type": "string" } } } }, "robotsBlocked": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "deprecated": true } }, "/v1/map": { "post": { "tags": [ "v1 aliases" ], "operationId": "mapV1", "summary": "v1 alias of POST /v2/map", "description": "اكتشاف روابط الموقع مع ترتيبها بكلمة بحث اختيارياً", "x-summary-ar": "اكتشاف روابط الموقع مع ترتيبها بكلمة بحث اختيارياً", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapRequest" }, "example": { "url": "https://example.com", "search": "pricing", "limit": 100 } } } }, "responses": { "200": { "description": "Links", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/MapLink" } } }, "required": [ "success", "links" ] }, "example": { "success": true, "links": [ { "url": "https://example.com/pricing", "title": "Pricing" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "deprecated": true } }, "/v1/search": { "post": { "tags": [ "v1 aliases" ], "operationId": "searchV1", "summary": "v1 alias of POST /v2/search", "description": "بحث في الويب والأخبار والصور بدمج مصادر مجانية متعددة مع جلب النتائج اختيارياً", "x-summary-ar": "بحث في الويب والأخبار والصور بدمج مصادر مجانية متعددة مع جلب النتائج اختيارياً", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" }, "example": { "query": "عجز الميزانية السعودية 2026", "limit": 5, "sources": [ "web", "news" ], "mode": "extended" } } } }, "responses": { "200": { "description": "Results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/SearchData" }, "creditsUsed": { "type": "number" } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "web": [ { "url": "https://example.com/a", "title": "…", "description": "…", "position": 1, "source": "bing+ddg" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "deprecated": true } }, "/v1/extract": { "post": { "tags": [ "v1 aliases" ], "operationId": "extractV1", "summary": "v1 alias of POST /v2/extract", "description": "بدء استخراج بيانات منظمة من روابط أو من الويب بمخطط أو تعليمات", "x-summary-ar": "بدء استخراج بيانات منظمة من روابط أو من الويب بمخطط أو تعليمات", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractRequest" }, "example": { "urls": [ "https://example.com/*" ], "prompt": "Company name and pricing plans", "schema": { "type": "object", "properties": { "company": { "type": "string" }, "plans": { "type": "array", "items": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "Job accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string", "description": "Job id" }, "url": { "type": "string", "description": "Status URL" } }, "required": [ "success", "id" ] }, "example": { "success": true, "id": "0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0", "url": "https://web-crawler.aleem-ai.com/v2/extract/0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "deprecated": true } }, "/v1/extract/{id}": { "get": { "tags": [ "v1 aliases" ], "operationId": "extractStatusV1", "summary": "v1 alias of GET /v2/extract/{id}", "description": "حالة الاستخراج ونتيجته", "x-summary-ar": "حالة الاستخراج ونتيجته", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id" } ], "responses": { "200": { "description": "Extract job status, progress and results (paged with next)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobView" }, "example": { "success": true, "status": "scraping", "total": 25, "completed": 9, "creditsUsed": 9, "expiresAt": "2026-11-04T19:00:00.000Z", "next": null, "progress": { "phase": "scrape", "pct": 36, "message_ar": "تُجلب الصفحات", "message_en": "Scraping pages" }, "data": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "deprecated": true } }, "/v1/team/credit-usage": { "get": { "tags": [ "v1 aliases" ], "operationId": "creditUsageV1", "summary": "v1 credit usage ({data: {remaining_credits}})", "description": "استهلاك الرصيد بصيغة v1", "x-summary-ar": "استهلاك الرصيد بصيغة v1", "deprecated": true, "responses": { "200": { "description": "Usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "remaining_credits": { "type": "number" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "webhooks": { "jobEvent": { "post": { "summary": "Webhook delivery for crawl / batch / extract / agent jobs", "description": "Events: .started, .page, .completed, .failed (kind: crawl | batch_scrape | extract | agent). Signed with HMAC-SHA256 of the raw body in X-Zahif-Signature (sha256=); the secret comes from GET /v2/zahif/webhook-secret.", "parameters": [ { "name": "X-Zahif-Signature", "in": "header", "schema": { "type": "string" }, "description": "sha256=" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "success": true, "type": "crawl.page", "id": "0f1e2d3c-…", "data": [ { "markdown": "…", "metadata": { "sourceURL": "https://example.com", "statusCode": 200 } } ], "metadata": { "project": "aleem" } } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "zh-<40 chars>", "description": "Authorization: Bearer zh-…" } }, "responses": { "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Unauthorized: Invalid token" } } } }, "PaymentRequired": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Admin scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Rate limit or monthly budget reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServerError": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Mode": { "type": "string", "enum": [ "fast", "extended", "deep", "custom" ], "default": "fast", "description": "fast = سريع; extended = مطوّل قليلاً; deep = مطوّل; custom = مخصص" }, "SettingsOverride": { "type": "object", "additionalProperties": true, "description": "Per-request settings (see GET /v2/zahif/settings/schema)" }, "Error": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "details": {} }, "required": [ "success", "error" ] }, "FormatType": { "type": "string", "enum": [ "markdown", "html", "rawHtml", "links", "images", "screenshot", "summary", "json", "changeTracking", "branding", "attributes", "query" ] }, "FormatSpec": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/FormatType" }, "schema": { "type": "object", "description": "JSON schema for type=json" }, "prompt": { "type": "string" }, "fullPage": { "type": "boolean" }, "quality": { "type": "integer" }, "viewport": { "type": "object", "properties": { "width": { "type": "integer" }, "height": { "type": "integer" } } }, "modes": { "type": "array", "items": { "type": "string" } }, "tag": { "type": "string" }, "selectors": { "type": "array", "items": { "type": "object", "properties": { "selector": { "type": "string" }, "attribute": { "type": "string" } } } }, "question": { "type": "string" } }, "required": [ "type" ] }, "Action": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wait", "click", "write", "press", "scroll", "screenshot", "scrape", "executeJavascript", "pdf" ] }, "milliseconds": { "type": "integer" }, "selector": { "type": "string" }, "text": { "type": "string" }, "key": { "type": "string" }, "direction": { "type": "string", "enum": [ "up", "down" ] }, "script": { "type": "string" }, "fullPage": { "type": "boolean" }, "all": { "type": "boolean" } }, "required": [ "type" ] }, "Location": { "type": "object", "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2", "default": "US" }, "languages": { "type": "array", "items": { "type": "string" } } } }, "ScrapeOptions": { "type": "object", "properties": { "formats": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/FormatType" }, { "$ref": "#/components/schemas/FormatSpec" } ] }, "description": "Default [\"markdown\"]" }, "onlyMainContent": { "type": "boolean", "description": "Strip navigation, headers, footers and boilerplate", "default": true }, "includeTags": { "type": "array", "items": { "type": "string" }, "description": "CSS selectors to keep" }, "excludeTags": { "type": "array", "items": { "type": "string" }, "description": "CSS selectors to drop" }, "maxAge": { "type": "integer", "description": "Accept a cached copy younger than this (ms)", "default": 172800000 }, "minAge": { "type": "integer", "description": "Only return a cached copy at least this old (ms)" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "waitFor": { "type": "integer", "description": "Extra wait after load (ms); renders with the browser" }, "mobile": { "type": "boolean", "description": "Mobile viewport and user agent", "default": false }, "skipTlsVerification": { "type": "boolean" }, "timeout": { "type": "integer", "description": "Request timeout (ms)", "default": 60000 }, "parsers": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "type": { "type": "string" }, "mode": { "type": "string" }, "maxPages": { "type": "integer" } } } ] }, "description": "Document parsers, e.g. [\"pdf\"]" }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/Action" } }, "location": { "$ref": "#/components/schemas/Location" }, "removeBase64Images": { "type": "boolean", "default": true }, "blockAds": { "type": "boolean", "default": true }, "proxy": { "type": "string", "enum": [ "basic", "stealth", "enhanced", "auto" ] }, "storeInCache": { "type": "boolean", "default": true }, "zeroDataRetention": { "type": "boolean", "description": "Never store page content or results", "default": false }, "fastMode": { "type": "boolean" }, "mode": { "$ref": "#/components/schemas/Mode" }, "settings": { "$ref": "#/components/schemas/SettingsOverride" } } }, "ScrapeRequest": { "allOf": [ { "$ref": "#/components/schemas/ScrapeOptions" }, { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] } ] }, "BatchScrapeRequest": { "allOf": [ { "$ref": "#/components/schemas/ScrapeOptions" }, { "type": "object", "properties": { "urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "webhook": { "$ref": "#/components/schemas/WebhookSpec" }, "maxConcurrency": { "type": "integer" }, "ignoreInvalidURLs": { "type": "boolean" } }, "required": [ "urls" ] } ] }, "WebhookSpec": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "metadata": { "type": "object" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "started", "page", "completed", "failed" ] } } }, "required": [ "url" ] } ] }, "CrawlRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "prompt": { "type": "string", "description": "Natural-language crawl intent" }, "excludePaths": { "type": "array", "items": { "type": "string" }, "description": "Regex patterns" }, "includePaths": { "type": "array", "items": { "type": "string" }, "description": "Regex patterns" }, "maxDiscoveryDepth": { "type": "integer" }, "sitemap": { "type": "string", "enum": [ "include", "only", "skip" ], "default": "include" }, "ignoreQueryParameters": { "type": "boolean" }, "regexOnFullURL": { "type": "boolean" }, "limit": { "type": "integer", "default": 10000 }, "crawlEntireDomain": { "type": "boolean" }, "allowExternalLinks": { "type": "boolean" }, "allowSubdomains": { "type": "boolean" }, "delay": { "type": "number", "description": "Seconds between requests" }, "maxConcurrency": { "type": "integer" }, "webhook": { "$ref": "#/components/schemas/WebhookSpec" }, "scrapeOptions": { "$ref": "#/components/schemas/ScrapeOptions" }, "zeroDataRetention": { "type": "boolean" }, "mode": { "$ref": "#/components/schemas/Mode" }, "settings": { "$ref": "#/components/schemas/SettingsOverride" } }, "required": [ "url" ] }, "MapRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "search": { "type": "string", "description": "Rank links by relevance to this term (BM25)" }, "sitemap": { "type": "string", "enum": [ "include", "only", "skip" ] }, "includeSubdomains": { "type": "boolean" }, "ignoreQueryParameters": { "type": "boolean" }, "limit": { "type": "integer", "default": 5000 }, "timeout": { "type": "integer" }, "location": { "$ref": "#/components/schemas/Location" }, "mode": { "$ref": "#/components/schemas/Mode" }, "settings": { "$ref": "#/components/schemas/SettingsOverride" } }, "required": [ "url" ] }, "MapLink": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" } }, "required": [ "url" ] }, "SearchRequest": { "type": "object", "properties": { "query": { "type": "string" }, "limit": { "type": "integer", "default": 5 }, "sources": { "type": "array", "items": { "oneOf": [ { "type": "string", "enum": [ "web", "news", "images" ] }, { "type": "object", "properties": { "type": { "type": "string" } } } ] } }, "categories": { "type": "array", "items": { "oneOf": [ { "type": "string", "enum": [ "github", "research", "pdf" ] }, { "type": "object", "properties": { "type": { "type": "string" } } } ] } }, "tbs": { "type": "string", "description": "Time filter, e.g. qdr:d, qdr:w, qdr:m, qdr:y" }, "location": { "type": "string" }, "country": { "type": "string" }, "timeout": { "type": "integer" }, "ignoreInvalidURLs": { "type": "boolean" }, "scrapeOptions": { "$ref": "#/components/schemas/ScrapeOptions" }, "mode": { "$ref": "#/components/schemas/Mode" }, "settings": { "$ref": "#/components/schemas/SettingsOverride" } }, "required": [ "query" ] }, "SearchHit": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "position": { "type": "integer" }, "category": { "type": "string" }, "source": { "type": "string", "description": "Backends that returned this hit" }, "date": { "type": "string" }, "imageUrl": { "type": "string" }, "markdown": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/DocumentMetadata" } }, "required": [ "url" ] }, "SearchData": { "type": "object", "properties": { "web": { "type": "array", "items": { "$ref": "#/components/schemas/SearchHit" } }, "news": { "type": "array", "items": { "$ref": "#/components/schemas/SearchHit" } }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/SearchHit" } } } }, "ExtractRequest": { "type": "object", "properties": { "urls": { "type": "array", "items": { "type": "string" }, "description": "URLs; a trailing /* expands to the site" }, "prompt": { "type": "string" }, "schema": { "type": "object" }, "enableWebSearch": { "type": "boolean" }, "ignoreSitemap": { "type": "boolean" }, "includeSubdomains": { "type": "boolean" }, "showSources": { "type": "boolean" }, "scrapeOptions": { "$ref": "#/components/schemas/ScrapeOptions" }, "ignoreInvalidURLs": { "type": "boolean" }, "mode": { "$ref": "#/components/schemas/Mode" }, "settings": { "$ref": "#/components/schemas/SettingsOverride" } } }, "AgentRequest": { "type": "object", "properties": { "prompt": { "type": "string", "description": "Research question" }, "urls": { "type": "array", "items": { "type": "string" } }, "schema": { "type": "object" }, "maxCredits": { "type": "integer" }, "strictConstrainToURLs": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "fast", "extended", "deep", "custom", "extract", "chat" ], "description": "Aleem AI Web Crawler work mode. Clients of the Firecrawl v2 API may send their own agent mode extract | chat: it is accepted, kept as the agent style, and the Aleem AI Web Crawler work mode then comes from zahifMode, the x-zahif-mode header or the key profile." }, "zahifMode": { "$ref": "#/components/schemas/Mode", "description": "Aleem AI Web Crawler work mode when `mode` carries extract | chat" }, "settings": { "$ref": "#/components/schemas/SettingsOverride" } }, "required": [ "prompt" ] }, "DocumentMetadata": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "language": { "type": "string" }, "sourceURL": { "type": "string" }, "url": { "type": "string" }, "statusCode": { "type": "integer" }, "contentType": { "type": "string" }, "error": { "type": "string" }, "scrapeId": { "type": "string" }, "cacheState": { "type": "string", "enum": [ "hit", "miss" ] }, "cachedAt": { "type": "string" }, "creditsUsed": { "type": "number" }, "engine": { "type": "string", "description": "Aleem AI Web Crawler extra: engine that produced the result" }, "elapsedMs": { "type": "integer" }, "quality": { "type": "number", "description": "Aleem AI Web Crawler extra: extraction quality 0..1", "minimum": 0, "maximum": 1 } }, "required": [ "sourceURL", "statusCode" ], "additionalProperties": true }, "Document": { "type": "object", "properties": { "markdown": { "type": "string" }, "html": { "type": "string" }, "rawHtml": { "type": "string" }, "links": { "type": "array", "items": { "type": "string" } }, "images": { "type": "array", "items": { "type": "string" } }, "screenshot": { "type": "string", "description": "URL or base64" }, "summary": { "type": "string" }, "json": {}, "changeTracking": {}, "branding": {}, "attributes": {}, "answer": { "type": "string" }, "actions": { "type": "object", "properties": { "screenshots": { "type": "array", "items": { "type": "string" } }, "scrapes": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "html": { "type": "string" } } } }, "javascriptReturns": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "value": {} } } }, "pdfs": { "type": "array", "items": { "type": "string" } } } }, "warning": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/DocumentMetadata" } }, "required": [ "metadata" ] }, "JobView": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "crawl", "batch", "extract", "agent" ] }, "status": { "type": "string", "enum": [ "scraping", "processing", "completed", "failed", "cancelled" ] }, "total": { "type": "integer" }, "completed": { "type": "integer" }, "creditsUsed": { "type": "number" }, "expiresAt": { "type": "string" }, "next": { "type": [ "string", "null" ], "description": "URL of the next page of results" }, "data": {}, "sources": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" } } } }, "error": { "type": "string" }, "progress": { "type": "object", "properties": { "phase": { "type": "string" }, "pct": { "type": "number" }, "message_ar": { "type": "string" }, "message_en": { "type": "string" } } } }, "additionalProperties": true }, "Usage": { "type": "object", "properties": { "remainingCredits": { "type": "number" }, "planCredits": { "type": "number" }, "billingPeriodStart": { "type": "string" }, "billingPeriodEnd": { "type": "string" } }, "required": [ "remainingCredits" ] }, "SettingSpec": { "type": "object", "properties": { "key": { "type": "string" }, "group": { "type": "string" }, "type": { "type": "string", "enum": [ "bool", "int", "float", "enum", "string", "list" ] }, "defaults": { "type": "object", "properties": { "fast": {}, "extended": {}, "deep": {} }, "required": [ "fast" ] }, "label_ar": { "type": "string" }, "label_en": { "type": "string" }, "help_ar": { "type": "string" }, "help_en": { "type": "string" }, "min": { "type": "number" }, "max": { "type": "number" }, "options": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "group", "type", "defaults", "label_ar", "label_en" ] }, "BrowserSessionRequest": { "type": "object", "properties": { "placement": { "type": "string", "enum": [ "auto", "serverless_edge", "serverless_container", "server", "device" ], "default": "auto" }, "display": { "type": "string", "enum": [ "none", "virtual", "real" ], "default": "none" }, "presence": { "type": "string", "description": "Human-like behaviour: off | natural | visible (cursor overlay and captions)", "enum": [ "off", "natural", "visible" ], "default": "off" }, "control": { "type": "string", "enum": [ "autonomous", "supervised", "handoff" ], "default": "autonomous" }, "stealth": { "type": "boolean", "default": false }, "profile": { "type": "string", "description": "Persistent named profile (cookies + storage, encrypted)" }, "deviceId": { "type": "string", "description": "Required for placement=device" }, "viewport": { "type": "object", "properties": { "width": { "type": "integer" }, "height": { "type": "integer" } } }, "locale": { "type": "string" }, "timezone": { "type": "string" }, "mobile": { "type": "boolean" }, "timeoutSec": { "type": "integer" }, "recording": { "type": "boolean" }, "startUrl": { "type": "string" }, "settings": { "$ref": "#/components/schemas/SettingsOverride" } } }, "BrowserSession": { "type": "object", "properties": { "id": { "type": "string" }, "placement": { "type": "string", "enum": [ "serverless_edge", "serverless_container", "server", "device" ] }, "display": { "type": "string", "enum": [ "none", "virtual", "real" ] }, "presence": { "type": "string", "enum": [ "off", "natural", "visible" ] }, "control": { "type": "string", "enum": [ "autonomous", "supervised", "handoff" ] }, "status": { "type": "string", "enum": [ "starting", "ready", "busy", "handoff", "closed", "failed" ] }, "url": { "type": "string" }, "title": { "type": "string" }, "tabs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "active": { "type": "boolean" } } } }, "liveViewUrl": { "type": "string" }, "deviceId": { "type": "string" }, "createdAt": { "type": "string" }, "expiresAt": { "type": "string" }, "creditsUsed": { "type": "number" }, "error": { "type": "string" } }, "required": [ "id", "placement", "display", "presence", "control", "status" ], "additionalProperties": true }, "BrowserAction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "navigate", "click", "dblclick", "type", "fill", "press", "scroll", "hover", "select", "check", "drag", "wait", "back", "forward", "reload", "tab_new", "tab_switch", "tab_close", "evaluate", "upload", "download", "screenshot", "snapshot", "extract", "pdf", "handoff" ] }, "ref": { "type": "string", "description": "Element ref from the aria snapshot (preferred), e.g. e12" }, "selector": { "type": "string" }, "x": { "type": "number" }, "y": { "type": "number" }, "toRef": { "type": "string" }, "text": { "type": "string" }, "key": { "type": "string" }, "url": { "type": "string" }, "value": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "direction": { "type": "string", "enum": [ "up", "down", "left", "right" ] }, "amount": { "type": "number" }, "ms": { "type": "integer" }, "until": { "type": "string", "enum": [ "load", "domcontentloaded", "networkidle", "selector", "text" ] }, "script": { "type": "string", "description": "evaluate only; off by default" }, "tabId": { "type": "string" }, "format": { "type": "string", "enum": [ "aria", "markdown", "som", "html" ] }, "fullPage": { "type": "boolean" }, "reason": { "type": "string" } }, "required": [ "type" ], "additionalProperties": true }, "BrowserActionResult": { "type": "object", "properties": { "ok": { "type": "boolean" }, "type": { "type": "string" }, "error": { "type": "string" }, "data": {}, "url": { "type": "string" }, "title": { "type": "string" }, "elapsedMs": { "type": "integer" } }, "required": [ "ok", "type" ] }, "BrowserSnapshot": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "format": { "type": "string", "enum": [ "aria", "markdown", "som", "html" ] }, "content": { "type": "string" }, "refs": { "type": "integer" }, "screenshot": { "type": "string" }, "truncated": { "type": "boolean" }, "diffFromPrevious": { "type": "boolean" } }, "required": [ "url", "format", "content" ] }, "Device": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "platform": { "type": "string" }, "online": { "type": "boolean" }, "lastSeen": { "type": "string" }, "browsers": { "type": "array", "items": { "type": "string" } } }, "required": [ "id" ] }, "Balance": { "type": "object", "properties": { "planCredits": { "type": "number" }, "planUsed": { "type": "number" }, "packCredits": { "type": "number" }, "reserved": { "type": "number" }, "available": { "type": "number" } } }, "Account": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "suspended", "cancelled" ] }, "planId": { "type": "string" }, "cycle": { "type": "string" }, "periodStart": { "type": "string" }, "periodEnd": { "type": "string" }, "balance": { "$ref": "#/components/schemas/Balance" }, "limits": { "type": "object" } }, "required": [ "id" ], "additionalProperties": true }, "PublicPlan": { "type": "object", "properties": { "id": { "type": "string" }, "name_ar": { "type": "string" }, "name_en": { "type": "string" }, "creditsPerMonth": { "type": "number" }, "concurrency": { "type": "integer" }, "rpm": { "type": "integer" }, "maxQueuedJobs": { "type": "integer" }, "packsAllowed": { "type": "boolean" }, "packCredits": { "type": [ "number", "null" ] }, "approved": { "type": "boolean" }, "priceMonthlySAR": { "type": "number", "description": "Only when the owner approved prices" }, "priceYearlySAR": { "type": "number" }, "packPriceSAR": { "type": "number" }, "priceNotice_ar": { "type": "string", "description": "When prices are not approved" }, "priceNotice_en": { "type": "string" } } }, "LedgerEntry": { "type": "object", "additionalProperties": true, "description": "ts, kind, op, credits, reason" }, "WebhookEvent": { "type": "object", "properties": { "success": { "type": "boolean" }, "type": { "type": "string", "description": "e.g. crawl.started, crawl.page, crawl.completed, crawl.failed, batch_scrape.page, extract.completed, agent.completed" }, "id": { "type": "string" }, "data": { "type": "array", "items": {} }, "metadata": { "type": "object" }, "error": { "type": "string" } }, "required": [ "type", "id" ] } } } }