API Edgepedia
بیش از ۵۰۰٬۰۰۰ مقالهٔ دانشنامهای، با تعدادی که پیوسته بیشتر میشود، در قالب JSON. رایگان. بدون کلید، بدون ثبتنام. استفادهٔ تجاری با ذکر منبع. آموزش هوش مصنوعی برای همه آزاد است.
امتحان کنید
- www.edgepedia.org/api/v1/search?q=koala
- www.edgepedia.org/api/v1/articles/koala
- www.edgepedia.org/api/v1/random
- www.edgepedia.org/api/v1/topics
مسیرهای خواندن از GET استفاده میکنند؛ مهاجرت، درخواستهای دستهای و متنی که میفرستید از POST. همهٔ مسیرها به هر برنامه یا صفحهٔ وبی با JSON پاسخ میدهند (CORS همهٔ مبدأها را مجاز میداند). شرح ماشینخوان: /openapi.json، با یک پاسخ نمونه برای هر مسیر؛ همین شرح در قالب OpenAPI 3.0، تعریف توابع برای مدلها، نوعهای TypeScript و مجموعهدرخواستها در بخش «فایلهای تولیدشده» در پایین آمدهاند.
کارتهای مرجع
انتخابشده: Cantor's diagonal argument
عنوان مقاله، خلاصهٔ کامل آن و نام Edgepedia بهعنوان منبع، در یک کارت برای وبسایت شما.
/embed/{id}?theme=auto کارت را بر اساس شناسهٔ اصلی مقاله ارائه میکند. ظاهر آن میتواند auto، light یا dark باشد. اسکریپت اختیاری /assets/edgepedia-embed.js اندازهٔ قاب را با محتوایش هماهنگ میکند؛ بدون آن هم قاب خوانا میماند و میتوان در آن پیمایش کرد.
/embed/{slug} هم کار میکند: با حفظ پوسته، به کارتِ شناسهٔ مقاله تغییرمسیر میدهد. Edgepedia ارائهدهندهٔ oEmbed هم هست: GET /oembed?url={article or card URL}&format=json همان کد جاسازیِ سازندهٔ بالا را بهصورت html، همراه با عنوان، عرض و ارتفاع برمیگرداند؛ maxwidth و maxheight نیز رعایت میشوند. در بخش <head> هر صفحهٔ مقالهٔ مجموعهٔ عمومی، پیوندی به نشانی oEmbed آن وجود دارد؛ بنابراین WordPress، Discourse و دیگر مصرفکنندگان oEmbed، پیوند Edgepedia را که در آنها جایگذاری شود به کارت تبدیل میکنند.
مسیرها
| مسیر | خروجی |
|---|---|
/api/v1/search?q=words | عنوانها و نامهای دیگر را تطبیق میدهد و بهترین تطابقها را اول میآورد. نام موضوع را جستوجو کنید، نه پرسش را. هر نتیجه شامل اینهاست: شناسه، عنوان، موضوع سطح اول، متن پیشنمایش، پیوندها و نحوهٔ تطبیق (match، confidence). عبارتهایی که نام یک موضوعاند، مانند «science fiction writers»، topics را hم برمیگردانند که پیوندی به مقالههای آن موضوع است. limit اندازهٔ صفحه است، از ۱ تا ۳۰ (پیشفرض ۱۰)؛ page صفحه را عوض میکند و صفحهای پس از آخرین صفحه خالی است. نامهای دیگر و املای نادرست هم کار میکنند: «zhu yuanzhang» امپراتور هونگوو را پیدا میکند و «siddartha» مقدار did_you_mean را برمیگرداند. گزینههای بیشتر: بخش «جستوجو» در پایین. |
/api/v1/articles/{slug} | مقاله در قالب Markdown، مسیر موضوعی آن، جایگاههایش در درخت جغرافیا (geo)، تاریخ آخرین بهروزرسانی و عبارت ذکر منبع که باید نمایش داده شود. هر نامی کار میکند (Mount_Fuji، عنوان یا نشانی کامل) و با گزینهها میتوان یک بخش، طرح کلی، گزیدههایی از متن یا شکلهای دیگر را دریافت کرد: بخش «خواندن مقاله» در پایین. |
/api/v1/articles?id={id} | همان خروجی، بر اساس شناسه. شناسههای قدیمی مقاله پس از مهاجرت پیکره هم همچنان به مقاله میرسند؛ شناسههای موضوع ممکن است با بازنگری درخت تغییر کنند. نشانی ممکن است جابهجا شود؛ نشانی قدیمی همچنان پاسخ میدهد، همراه با moved_from. ids= تا ۱۰ مورد را همزمان میپذیرد. |
/api/v1/leads?ids={id},{id} | حداکثر ۵۰ مقاله بر اساس شناسه، هرکدام بهشکل یک نتیجهٔ جستوجو (شناسه، عنوان، موضوع سطح اول، متن پیشنمایش و پیوندها)، برای صفحهای از کارتها. شناسههای مهاجرتکرده و ادغامشده، مقالهٔ باقیمانده را برمیگردانند و کلیدشان همان شناسهٔ درخواستی است؛ id در نتیجه، شناسهٔ اصلی است. شناسههای ناشناخته یا در دسترسنبوده حذف میشوند. |
/api/v1/random | یک مقالهٔ تصادفی. new=1 از میان تازهترین مقالهها انتخاب میکند؛ topic= یا geo= از زیرمجموعهٔ یک گره انتخاب میکند. |
/api/v1/related/{slug} | همسایههای یک مقاله با یک فراخوانی: حداکثر ۱۰ تا از نزدیکترین مقالهها به آن در موضوع خودش، ۳ مقاله از هرکدام از حداکثر ۸ موضوع همسایه و حداکثر ۱۰ تا از نزدیکترین مقالهها به آن در هریک از گرههای جغرافیایی که در آن قرار دارد. همچنین ?id={id}. در عوض، by=links مقالههایی را میدهد که همراه با آن مورد استناد قرار گرفتهاند. |
/api/v1/topics | رأس درخت موضوعی. |
/api/v1/topics/{id} | مسیر یک موضوع، زیرموضوعهای آن با تعداد مقالههایشان، و همهٔ مقالههای زیرمجموعهٔ آن، هر صفحه ۳۰ مقاله. format=mermaid زیردرخت آن را ترسیم میکند. |
/api/v1/geo | درخت جغرافیا: منطقههای آن، هرکدام همراه با دورههایشان. |
/api/v1/geo/{id} | یک گرهٔ جغرافیایی، با ساختاری مانند موضوع: مسیر آن، گرههای جزئیتر و مقالهها، هر صفحه ۳۰ مقاله. هر منطقه فقط دورههای خود را فهرست میکند. |
POST /api/v1/ids/translate | در صورت فعال بودن مهاجرت نسخهٔ 1.5: مقدار {"ids":["old-id", "another-id"]} را بفرستید (حداکثر ۵۰۰ شناسهٔ متمایز). پاسخ، شناسههای جابهجاشده را به شناسههای اصلیِ باقیمانده نگاشت میکند؛ شناسههای بدون تغییر یا ناشناخته حذف میشوند. پیشرفت دستههای تکمیلشده را ثبت کنید و Retry-After را رعایت کنید. |
متن پیشنمایش، در صورت وجود، از چکیدهٔ کوتاه پیکره استفاده میکند و در غیر این صورت از ابتدای مقاله. رکوردها و نتایجی که چکیدهٔ کوتاه دارند، آن را با نام snippet هم در بر میگیرند؛ markdown همچنان متن کامل مقاله است. node، اگر موجود باشد، گرهٔ فعلی مقاله در درخت مفهومی است.
هر مقاله در نشانی خودش بهصورت Markdown هم در دسترس است. .md را اضافه کنید: www.edgepedia.org/koala.md.
سرور MCP
https://www.edgepedia.org/mcp. آن را بهعنوان اتصالدهندهٔ سفارشی به Claude، با روشن بودن حالت توسعهدهنده به ChatGPT، با یک کلیک به VS Code یا Cursor، یا با نشانیاش به هر کلاینت MCP دیگری اضافه کنید. بدون کلید، بدون ورود به حساب. پنج ابزار فقطخواندنی: search (نام موضوع را میگیرد و مقالههای منطبق را برمیگرداند؛ اگر عبارت نام یک موضوع باشد، آن موضوع را هم برمیگرداند)، fetch (یک مقاله در قالب Markdown، همراه با عبارت ذکر منبع، مسیر موضوعی و جغرافیای آن؛ citations: false برای متنی تقریباً یکچهارم کوتاهتر؛ شناسهٔ topic:، موضوع والد، موضوعهای جزئیتر و مقالههای آن موضوع را فهرست میکند، با ۱۲۰ مقاله در هر page؛ topic:root و topic:geo رأس درخت موضوعی و درخت جغرافیا هستند)، related (همسایههای مقاله در موضوع خودش، موضوعهای نزدیک و جغرافیا؛ by: "links" برای مقالههایی که همراه با آن مورد استناد قرار گرفتهاند)، connect (from، to: زنجیرهٔ پیوندهای میان دو مقاله، بهشکلی که /api/v1/path ارائه میکند)، و resolve (name، با context و type اختیاری: مقالهای که بهاحتمال زیاد منظور از یک نام است، بهشکلی که /api/v1/resolve ارائه میکند). وقتی عنوانی با جستوجوی search منطبق نباشد، مقالههایی که متنشان منطبق است پس از تطابقهای عنوان میآیند، با نشان match: fulltext، در محدودهٔ limit و با احتساب در pages. خطای ابزار متنی است که مدل میخواند (همراه با شناسههای did_you_mean برای شناسهای که هیچ مقالهای ندارد)؛ کد آن در _meta["ai.edgechat/error"] میآید، نه هرگز در structuredContent. ابزار fetch با links: "in"، مقدار links_page را برای ۳۰ مقالهٔ بعدی که به آن پیوند میدهند میپذیرد.
search گزینههای limit (۱ تا ۳۰، پیشفرض ۱۰)، page، first، topic و sort را میپذیرد و page و pages را در پاسخ میدهد؛ fetch گزینههای مقاله در پایین و ids را برای چند مورد همزمان میپذیرد. هر نتیجه شامل canonical_id است، یعنی شناسهٔ دائمی مقاله: fetch آن را میپذیرد و اگر شناسه یا نشانی ذخیرهشدهٔ شما جابهجا شده باشد، fetch مقاله را با moved_from برمیگرداند که مقدارش همان چیزی است که درخواست کردهاید. نتایج، انتشار پیکره را در _meta.corpus_version مشخص میکنند. کلاینتهای مبتنی بر پروتکل 2025-06-18 یا جدیدتر، بهازای هر مقاله یک resource_link هم دریافت میکنند.
منابع: edgepedia://article/{slug} (مقاله در قالب Markdown، همان متن fetch) و edgepedia://topic/{id} (موضوعهای جزئیتر و مقالههای یک موضوع)، هر دو با قابلیت تکمیل؛ قابلیت تکمیل همچنین برای هر آرگومانی که نام مقاله میگیرد، عنوان مقاله پیشنهاد میکند. مهارت عامل نیز از طریق MCP ارائه میشود (skills/list، skills/get)، بهصورت skill://edgepedia/SKILL.md. یک درخواست GET به /mcp، کارت سرور را در قالب JSON برمیگرداند. کلاینتهایی که فقط text/event-stream را میپذیرند، هر پاسخ را بهصورت یک رویداد message از نوع SSE دریافت میکنند. مقدار sha256 فهرست ابزارها در _meta هر پاسخ میآید (ai.edgechat/tools-sha256)، تا تغییر توضیحات هر ابزار قابل مشاهده باشد.
Windows (پیشنمایش، بیلد 26220.7262 یا جدیدتر): odr.exe mcp add --uri https://www.edgepedia.org/mcp. دستورهای راهاندازی برای همهٔ کلاینتهای دیگر، یک مهارت عامل و مثالها: github.com/EdgePlat/edgepedia-mcp.
MCP ندارید، یا کلاینتتان فقط از روش انتقال قدیمی SSE پشتیبانی میکند؟ دو تابع در اختیار مدل خود بگذارید که /api/v1/search و /api/v1/articles/{slug} را فراخوانی کنند، یا نسخهٔ آمادهٔ آنها را از /tools.json بگیرید. نشانیهای روش انتقال قدیمی (/sse، /mcp/sse) پاسخ 404 میدهند و در بدنهٔ پاسخ، https://www.edgepedia.org/mcp را معرفی میکنند.
محدودیتها
۶۰۰ درخواست در دقیقه و ۱۰۰٬۰۰۰ درخواست در روز بهازای هر نشانی IP، هم برای API و هم برای سرور MCP. هر پاسخ، هر دو بازه را در RateLimit-Policy مشخص میکند. پس از عبور از این حدها، API پاسخ 429 را همراه با Retry-After و RateLimit برمیگرداند؛ فراخوانی ابزار MCP خطای ابزاری برمیگرداند که retry_after آن، زمان را به ثانیه میدهد. شمارش برای هر نمونهٔ سرور جداگانه انجام میشود؛ بنابراین این اعداد سقفیاند که باید زیر آن بمانید، نه سنجهای دقیق. لطفاً از حافظهٔ نهان استفاده کنید. در تبدیل شناسهها (/ids/translate)، هر شناسهٔ درخواستی جداگانه شمرده میشود؛ دستههای /leads که شناسههای قدیمی را بررسی میکنند نیز بهازای هر شناسهٔ قدیمی محاسبه میشوند. در دیگر درخواستهای دستهای، هر شناسه یا نام یک درخواست به حساب میآید و در annotate، هر ۱٬۰۰۰ نویسه یک درخواست.
مجوز
مجوز جامعهٔ کاربری Edgepedia، نسخهٔ ۱٫۰: رایگان با ذکر منبع، شامل استفادهٔ تجاری. آموزش هوش مصنوعی برای همه آزاد است و خروجی مدل نیازی به ذکر منبع ندارد. برای دیگر کاربردها، سازمانهایی با بیش از ۱۰۰ میلیون دلار آمریکا درآمد یا ۱۰۰ میلیون کاربر ماهانه باید مجوز جداگانه بگیرند.
ذکر منبع: هرجا متن مقالهای را نمایش میدهید، عبارت credit آن را همراه با پیوندش نشان دهید. پاسخهای مقاله، این عبارت را بهشکل آماده برای جایگذاری در credit_md و credit_html، و نیز license.spdx (LicenseRef-Edgepedia-Community-1.0) در بر دارند. پاسخهای API برای مقالهها و برای /leads شامل Link: <https://www.edgepedia.org/edgepedia/license>; rel="license" و X-License: LicenseRef-Edgepedia-Community-1.0 هستند.
برنامهٔ EdgeChat، برنامههای Edge Apps آن و نرمافزارهای ما رایگان اما مالکیتیاند: کد منبع ارائه نمیشود و کپی، تغییر یا بازتوزیع آنها مجاز نیست (توافقنامهٔ مجوز EdgeChat).
خطاها
JSON: { "error": { "code": "not_found", "message": "…" } }. 400 نبودِ q، 404 یافت نشد، 410 حذف شده، 413 متن بیش از حد طولانی، 429 تعداد درخواست بیش از حد، 503 دوباره تلاش کنید. پاسخ 404 فراخوانی بعدی را مشخص میکند: hint، next (یک URL) و، برای نشانی مقالهای که هیچ پاسخی ندارد، did_you_mean با سه عنوان از نزدیکترین عنوانها. خطای «یافت نشد» ابزار fetch در MCP نیز همین did_you_mean را در بر دارد.
تغییرات
نسخهٔ ۱ ساختار خود را حفظ میکند: ممکن است فیلدهایی اضافه شوند، اما هیچ فیلدی تغییر نام نمییابد یا حذف نمیشود. تغییرات خود Edgepedia در /edgepedia/updates آمدهاند. وقتی یک انتشار، درخت موضوعی را بازآرایی کند، چنانکه در نسخهٔ 1.8.0 رخ داد، شناسهٔ موضوعی که جابهجا شده است پاسخ 301 را با شناسهٔ جدیدش برمیگرداند و /api/v1/changes?since=<release> همهٔ مقالههایی را که از آن انتشار به بعد اضافه، تغییر، جابهجا یا حذف شدهاند فهرست میکند.
/api/v1 مقادیر corpus_version، corpus_updated و release_notes را گزارش میکند. اینها انتشارِ عرضهشدهٔ پیکرهٔ عمومی و تاریخ انتشار آن را مشخص میکنند، نه تاریخ آخرین ویرایش تکتک مقالهها را. همین فراداده در دستورالعملهای سرور MCP هم میآید. انتشارهای پیکره، نسخهٔ نرمافزار API یا MCP را تغییر نمیدهند. id_policy در آنجا میگوید یک شناسه چه تضمینی دارد: ممکن است در یک انتشار، شناسهها دوباره شمارهگذاری یا ادغام شوند، چنانکه در نسخهٔ 1.5 شد؛ شناسههای قدیمی از طریق پاسخ 308 و POST /api/v1/ids/translate همچنان پاسخ میدهند.
چیزی درست کار نمیکند؟ گزارش کنید.
مرجع
مسیرها و فیلدهایی که از دادههای مشتقشده خوانده میشوند (اهمیت، سطح خوانایی، پیوندها، تاریخها، نامهای دیگر و نمایهٔ تماممتن)، تا زمانی که آن دادهها همراه با مخزن داده منتشر شوند، پاسخ 503 با Retry-After میدهند یا آن فیلد را حذف میکنند.
خواندن مقاله
/api/v1/articles/{slug} و ابزار fetch در MCP این گزینهها را میپذیرند؛ بدون آنها، پاسخ شامل تمام مقاله است.
| گزینه | خروجی |
|---|---|
section={heading} | یک بخش، بر اساس عنوان آن یا واژهای از عنوانش (section=etymology بخش «نام و ریشهشناسی» را پیدا میکند؛ section=lead بخش آغازین است)، همراه با زیربخشهایش. عنوان ناشناخته، پاسخ 404 را همراه با sections مقاله برمیگرداند. |
outline=1 | outline: همهٔ عنوانها همراه با اندازهٔ هرکدام به توکن. |
max_tokens={n} | متنِ کوتاهشده تا حدود n توکن، با برش در مرز بخش یا بند، همراه با tokens_estimate، truncated و next_cursor؛ برای دریافت ادامه، آن را بهصورت cursor با همان max_tokens بفرستید. |
length=snippet، length=lead | چکیدهٔ کوتاه، یا عنوان و بند آغازین، بهجای تمام متن. |
format=text، html، jsonld، turtle، tables | پاسخ بهصورت متن ساده، بدنهٔ رندرشده، یا فیلدهای عمومی در قالب JSON-LD یا Turtle؛ tables هر جدول را بهصورت columns و rows، بهشکل csv و با انتقال ارجاعهای آن به cites و sources ارائه میکند. |
chunks=1 | chunks: مقاله بهصورت بندهایی که هرکدام شناسهای پایدار برگرفته از مسیر عنوانهای خود (geology-2) و یک cite_url دارند. |
q={words}&k={1–10} | passages: تعداد k بند (پیشفرض ۳) که بیشترین تطابق را با واژهها دارند، هرکدام همراه با یک cite_url. |
quote={sentence or chunk id} | cite_url: نشانی مقاله همراه با قطعهمتنی که صفحه را در محل آن گزیده باز میکند؛ quote_found میگوید آیا مقاله آن را در بر دارد یا نه. |
cite={format} | cite: ارجاعی به مقاله، بهشکلی که /api/v1/cite ارائه میکند. |
هر پاسخ مقاله، speakable را هم در بر دارد (چکیدهٔ کوتاه بهشکلی که دستیار صوتی بتواند آن را بخواند). importance و rank (پیجرنک بر پایهٔ پیوندهای میان مقالهها؛ ۱ مرکزیترین است؛ شمارش پیوندهاست، نه داوری دربارهٔ موضوع)، words، reading_grade (فلش–کینکید) و reading_minutes فقط هنگامی میآیند که fields= آنها را نام ببرد (?fields=title,importance,rank)؛ ابزار fetch در MCP همیشه آنها را دارد. next=1 حداکثر ۵ مقاله برای مطالعهٔ بعدی اضافه میکند. citations=false در markdown، chunks و passages بهجای پیوندهای درونمتنی منابع، نشانههای [n] میگذارد، همان کاری که citations: false در MCP میکند. نشانیای که به هیچ مقالهای تعلق ندارد، شناسهٔ مقاله (/api/v1/articles/ep7rbwcy0a) یا عنوان آن تلقی میشود، بیاعتنا به بزرگی و کوچکی حروف و نشانههای آوایی (/api/v1/articles/paris)؛ اگر نشانیای با حروف کوچک و خط تیره از این هم فاصلهٔ بیشتری داشته باشد، پاسخ 404 میگیرد، مگر اینکه ?suggest=1 را اضافه کنید؛ اما نشانیِ دارای حروف بزرگ، فاصله یا زیرخط (/api/v1/articles/Albert_Einstein) نام تلقی میشود و بنابراین اگر نزدیک به نام درست باشد، بهترین تطابق جستوجو را همراه با resolved_by: search برمیگرداند. وقتی نامی که دادهاید نشانی مقاله نباشد، پاسخ میگوید آن را چگونه تفسیر کرده است (resolved_from، resolved_by: نشانی، عنوان یا جستوجو) و ۳ مقالهٔ دیگر را در nearest فهرست میکند. /api/v1/articles?ids={slug or id},{name} حداکثر ۱۰ مورد را بهصورت articles (هرکدام با نامی که به آن پاسخ میدهد در asked) و missing برمیگرداند؛ هر گزینه بر تکتک موارد اعمال میشود.
استناد به مقاله
/api/v1/cite/{slug}?format= یک ارجاع در قالب csl (CSL-JSON، پیشفرض)، bibtex، ris، apa، mla، chicago یا harvard میدهد، همراه با عبارت ذکر منبع بهصورت متن، Markdown و HTML؛ /api/v1/cite?ids={id},{slug} همین کار را برای حداکثر ۵۰ مورد انجام میدهد. نویسنده Edgepedia (EdgeChat) است؛ APA، MLA، شیکاگو و هاروارد، مانند Markdown، عنوانِ ایتالیک را با ستاره مشخص میکنند. کارتهای مرجع همین ارجاع را بهصورت نامرئی، در قالب COinS و JSON-LD، برای نرمافزارهای مدیریت منابع در بر دارند.
جستوجو
match | چه وقت | confidence |
|---|---|---|
exact | عنوان همان عبارت جستوجو است. | ۱٫۰ برای نخستین نتیجه از این نوع، ۰٫۹ برای نتیجههای بعدی |
alias | نامی دیگر یا حروف اول واژههای عنوان («mlk») منطبق بوده است. | ۰٫۸؛ ۰٫۷ برای نخستین نتیجهای که هیچ واژهای از عبارت جستوجو را ندارد؛ ۰٫۶ برای عبارت جستوجوی نویسهگردانیشده |
misspelling | جستوجو عبارت را اصلاح کرده است (did_you_mean). | ۰٫۵ × سهمی از عبارت تایپشده که در اصلاح حفظ شده است |
partial | بعضی واژههای عبارت جستوجو در عنوان، یا فقط در متن، آمدهاند. | ۰٫۲ + ۰٫۵ × سهم واژههای عبارت جستوجو که در عنوان آمدهاند؛ ۰٫۲ برای تطابق فقط در متن |
fulltext | هیچ عنوان یا نام دیگری منطبق نبوده، پس متن مقالهها جستوجو شده است (BM25): یک توصیف، مقالهای را پیدا میکند که نامش را نمیدانید. | دستکم ۰٫۲ |
none | هیچ تطابقی پیدا نشده است. پاسخ خالی است. | ۰ |
میزان اطمینان تابع قاعدهای ثابت است، نه یک احتمالِ واسنجیشده؛ پاسخی که امتیاز بهترین نتیجهاش کمتر از ۰٫۲ باشد، خالی برمیگردد. هر نتیجه شامل highlight است: جملهای از خلاصهٔ آن که بیشترین واژههای عبارت جستوجو را در خود دارد. جستوجویی که چیزی پیدا نکند، یک بار دیگر با حروف لاتین انجام میشود (سیریلیک، یونانی، کانا و هانگول نویسهگردانی میشوند، اعداد نواخت در پینیین حذف و مصوتهای دوتایی روماجی کوتاه میشوند) و پاسخ آن را در searched_as مشخص میکند. نویسههای چینی نویسهگردانی نمیشوند.
| گزینه | کارکرد |
|---|---|
first=true | فقط بهترین تطابق، یا هیچ نتیجهای. |
topic={id}، geo={id} | فقط مقالههای زیرمجموعهٔ آن موضوع یا گرهٔ جغرافیایی؛ geo همهٔ تطابقها را تا سقف ۱٬۰۰۰ مورد فیلتر میکند و scope محدودهٔ پوشش پاسخ را مشخص میکند. |
sort=central | از میان همهٔ تطابقها تا سقف ۱٬۰۰۰ مورد، موضوعهایی که بیشترین پیوند را دارند اول میآیند. |
max_grade={grade} | فقط مقالههایی در آن پایهٔ تحصیلیِ خوانایی یا پایینتر. |
facets=1 | تعداد تطابقها به تفکیک موضوع سطح اول و منطقهٔ جغرافیایی، در میان همهٔ تطابقها تا سقف ۱٬۰۰۰ مورد (facets.counted). |
همهٔ پاسخها
fields=a,b فقط همان کلیدها را از هر نتیجه نگه میدارد (یا از خود پاسخ، وقتی نتیجهای ندارد)؛ پوشش پاسخ (total، page، next، license) باقی میماند. پاسخ 200 که بتوان آن را در حافظهٔ نهان ذخیره کرد، شامل ETag است: آن را بهصورت If-None-Match پس بفرستید تا اگر پاسخ تغییری نکرده باشد، 304 بدون بدنه برگردد. Last-Modified تاریخ انتشار پیکره است و فقط جنبهٔ اطلاعرسانی دارد. Edgepedia-Corpus-Version انتشار پیکره را مشخص میکند و Content-Digest مقدار SHA-256 بدنه است (RFC 9530)؛ .md هر مقاله هم هر دو را دارد.
مسیرهای بیشتر
| مسیر | خروجی |
|---|---|
/api/v1/articles?after={id}&limit={1..1000} | همهٔ مقالههای مجموعهٔ عمومی، با پیمایش بهترتیبی ثابت: {id, slug, title, api_url} و next (در پایان null). after= خالی، پیمایش را از ابتدا آغاز میکند و ادامهٔ پیمایش از پسِ هر شناسهای ممکن است، حتی شناسهای حذفشده. |
/api/v1/trees، /api/v1/trees/topic، /api/v1/trees/geo | درخت موضوعی و درخت جغرافیا بهطور کامل: nodes: [[id, label, parent index, own articles]]؛ شناسهای که با نقطه آغاز شود ادامهٔ شناسهٔ والدش است. |
/api/v1/releases | انتشارهای پیکره، از تازهترین به قدیمیترین، و current. |
/api/v1/health | application/health+json: pass، warn یا fail (503). |
/api/v1/manifest | تغییرمسیر به یک فایل JSONL فشردهشده با gzip، با یک خط برای هر مقاله: { id, slug, title, updated, sha256, topic } (sha256 از .md مقاله). برای ساخت نسخهٔ آینهای Edgepedia آن را یک بار دریافت کنید. جمع کنترلی مربوط به متن منتشرشده، پیش از اصلاحات خوانندگان است: مقالهای که از زمان انتشار بر اثر گزارش یک خواننده اصلاح شده باشد، تا انتشار بعدی با آن تطابق نخواهد داشت. |
/api/v1/changes?since={release} | فایلهای تغییرات از آن انتشار تا انتشار فعلی، بهترتیب (خوراک از نسخهٔ 1.5 آغاز میشود: since=1.5 نخستین مورد است)؛ هر خط { op, id, … } است و op یکی از اینهاست: added، changed، moved (from_slug نشانی قدیمی است) یا removed. |
/api/v1/events/{slug} | جملههای مقاله که تاریخی را بیان میکنند: { date, precision, text, para }، date بهصورت YYYY، YYYY-MM یا YYYY-MM-DD (برای پیش از میلاد منفی است: -0044-03-15). تاریخهای پیش از میلاد از قرارداد تاریخی پیروی میکنند، نه سالشماری نجومی: -0044 یعنی ۴۴ پیش از میلاد (یک تجزیهگر استاندارد ISO 8601 آن را ۴۵ پیش از میلاد میخواند). شاهد همان جمله است: پیش از آنکه تاریخ را واقعیتی مسلم بدانید، جمله را بخوانید. |
/api/v1/aliases/{id} | نامهای دیگر مقاله، از جمله سرواژههایی که در مقالهها آمدهاند («NASA»)؛ املای نادرست و صورتهایی که فقط در بزرگی و کوچکی حروف تفاوت دارند کنار گذاشته میشوند و از دو املای یک نام، صورت بینقطه نگه داشته میشود («WHO»، نه «W.H.O.»). |
تعیین مصداق، حاشیهنویسی و تطبیق موجودیتها
ورودی متن آزاد است و خروجی شناسهٔ مقالهها، بدون مدل و بدون بردارهای تعبیه. متنی که به annotate، classify و geoparse میفرستید هرگز ثبت یا نگهداری نمیشود.
| مسیر | خروجی |
|---|---|
/api/v1/resolve?name=Mercury&context=planet | مقالهای که بهاحتمال زیاد منظور از یک نام است: result، confidence، ambiguous، match (exact، alias، anchor، partial یا none) و alternatives. type= نامزدها را به زیرمجموعهٔ یک شناسهٔ موضوع محدود میکند (اگر هیچیک از ۳۰ تطابق نخست نام در آنجا نباشد، برای یک نام منفرد، ۶۰ تطابق بعدی هم بررسی میشود)؛ limit= از ۱ تا ۱۰ است. POST حداکثر ۵۰ مورد میپذیرد: { "names": ["Paris", "Koala"] } یا { "queries": [{ "name": "Mercury", "context": "planet" }] }. نامی که بهتنهایی یک مقاله را مشخص نکند، پاسخ ambiguous: true میگیرد و بهترین حدس در result میآید؛ برای انتخاب، context را بفرستید. |
/api/v1/surface?form=mercury | همهٔ مقالههایی که پیوندهای خود پیکره با این عبارت دقیق به آنها اشاره کردهاند، همراه با تعداد پیوندها و سهم هر مقاله (commonness). |
/api/v1/suggest?prefix=koa | نخست مقالهای که عنوانش دقیقاً همان عبارت است، سپس مقالهای که یکی از نامهای دیگرش دقیقاً همان است، سپس عنوانهایی که با آن پیشوند آغاز میشوند و بعد نامهای دیگری که چنیناند (matched آن نام را میدهد)، برای کادرهای جستوجو و رابطهای صوتی. |
POST /api/v1/annotate | { "text": "…" } (حداکثر ۲۰٬۰۰۰ نویسه): هر عبارت پیوندخورده همراه با موقعیتهایش (start، end، بر حسب واحدهای کد UTF-16، همانطور که JavaScript رشتهها را نمایهگذاری میکند: در Python، نویسهای بیرون از صفحهٔ چندزبانهٔ پایه، مانند ایموجی، دو واحد حساب میشود)، مقاله و میزان اطمینان. ?format=html متن را هم با نویسههای ویژهٔ HTML تبدیلشده به صورت امن و هر عبارت بهشکل پیوند برمیگرداند. |
POST /api/v1/classify | { "text": "…" }: موضوعهایی که متن دربارهٔ آنهاست، با امتیازدهی بر اساس مسیرهای موضوعی مقالههایی که از آنها نام میبرد، و سهم موضوعهای سطح اول. |
POST /api/v1/geoparse | { "text": "…" }: مکانها و دورههایی که متن نام میبرد، روی درخت جغرافیا (nodes، regions، places، periods)؛ شاخهٔ غیرجغرافیایی درخت (geo.nongeo) هرگز مکان محسوب نمیشود. |
/api/v1/mentions?term=CRISPR | مقالههایی که از موضوعی نام میبرند، بیآنکه به مقالهٔ آن پیوند بدهند؛ complete: false یعنی فهرست مقالههای پیونددهنده کوتاه شده است. |
/api/v1/reconcile | یک نقطهٔ پایانی API سرویس تطبیق موجودیتها، نسخهٔ 0.2: مانیفست، queries دستهای (GET یا POST)، پیشنهاد موجودیت، نوع و ویژگی، پیشنمایش و گسترش دادهها (title، url، excerpt، topic، topic_path، importance_rank). JSONP با callback=. در OpenRefine: گزینههای Reconcile › Start reconciling › Add standard service را دنبال کنید و https://www.edgepedia.org/api/v1/reconcile را جایگذاری کنید. |
گراف پیوندها، تاریخها و فهرستها
نمودارها (format=mermaid) متن Mermaid هستند، برای میزبانی که آن را رندر میکند.
| مسیر | خروجی |
|---|---|
/api/v1/links/{slug} | پیوندهای مقاله به مقالههای دیگر، بهترتیب خواندن، هرکدام همراه با متن پیوند و جملهاش. |
/api/v1/backlinks/{slug}?page= | مقالههایی که به آن پیوند میدهند، هر صفحه ۳۰ مورد، از مهمترین به کماهمیتترین، همراه با متن پیوندشان. |
/api/v1/path?from=&to= | کوتاهترین زنجیرهٔ پیوندها میان دو مقاله (حداکثر ۶ گام، با پرهیز از گرههای قطب تا حد امکان)، همراه با جملهای که هر گام را برقرار میکند. سرور MCP آن را connect مینامد. |
/api/v1/compare?a=&b= | دو مقاله در کنار هم: بخشهای آغازین، مسیرهای موضوعی، جزئیترین موضوع مشترک، زنجیرهٔ میان آنها، پیوندهای مشترک و اختصاصی، و جدول «واقعیتهای کلیدی» هرکدام. |
/api/v1/graph/{slug}?depth=1|2&limit= | حداکثر limit مورد (پیشفرض ۵۰، حداکثر ۲۰۰) از مهمترین همسایههای آن و همهٔ پیوندهای میان آنها. complete: false (در اینجا، در backlinks و در rank/top) یعنی مهلت زمانی حدوداً یکثانیهای مسیر، پاسخ را کوتاه کرده است؛ چنین پاسخی فقط یک دقیقه در حافظهٔ نهان نگه داشته میشود. |
POST /api/v1/context | { "ids": [...] }، حداکثر ۵۰ شناسه یا نشانی (همانطور که /rank?ids= و /leads?ids= هم آنها را میپذیرند): پیوندهای میان آنها، مقالههایی که بیشترین تعدادشان با آنها پیوند دارند، جزئیترین موضوع و مکان مشترک، و بخش آغازین هرکدام. |
/api/v1/rank?ids=، /api/v1/rank/top?topic=&limit= | اهمیت بر اساس پیجرنک: مجموع pr در کل پیکره ۱ است و رتبهٔ ۱ مرکزیترین است. به نامها توجه کنید: importance در /search و مقالهها، این رتبه را بهصورت صدکی در بازهٔ ۰ تا ۱ نشان میدهد؛ importance در /resolve همان pr خام است و در /leads برابر با { pr, rank } است. |
/api/v1/timeline?topic=|geo=&from=&to= | جملههای تاریخدار از مقالههای یک موضوع یا مکان، از قدیمیترین به تازهترین، هر صفحه ۵۰ مورد؛ سالهای پیش از میلاد منفیاند. هر گره حداکثر ۲۰۰ رویداد را با پراکندگی در تاریخهایش نگه میدارد و from و to همان نمونه را فیلتر میکنند؛ پاسخی که از نمونهای با ظرفیت کامل گرفته شده باشد، sampled: true و cap خود را اعلام میکند و total آن، تعداد موارد نمونه را میشمارد. |
/api/v1/onthisday?date=MM-DD، /api/v1/year/{year} | رویدادهای یک روز از سال (بهطور پیشفرض، امروز به وقت UTC)، یا یک سال (از -۹۹۹۹ تا ۲۱۰۰). هر روز حداکثر ۵۰۰ رویداد و هر سال ۲٬۰۰۰ رویداد دارد؛ اگر ظرفیت پر شده باشد، sampled: true اعلام میشود. |
/api/v1/featured?date=، /api/v1/featured.xml | مقالهٔ برگزیدهٔ روز (بخش «دانستنی امروز» در صفحهٔ ورودی) و یک خوراک Atom از ده روز گذشته. |
/api/v1/list?topic=|geo=&period=&type=person | مقالههای یک موضوع، یا یک مکان و دوره (TBC، T500، T1000، T1800، T1946، T2001، T2021، NODATE)، هر صفحه ۳۰ مورد؛ type=person فقط اشخاص را نگه میدارد. ردیفهای فهرست جغرافیایی، geo دارند و id ندارند (برای آن، خود مقاله را دریافت کنید). |
/api/v1/keyterms?topic=|geo=&limit= | عنوانها و نامهای دیگر یک زیردرخت، برای آمادهسازی سامانهٔ بازشناسی گفتار. |
/api/v1/stats?topic=|geo=&by=period | فقط تعدادها: مقالهها، پیوندها و نامهای دیگر برای پیکره یا یک گره و فرزندانش. در اینجا articles مقالههای متمایز را میشمارد؛ در /geo و /trees/geo جایگاهها را میشمارد، پس مقالهای که در دو دورهٔ یک منطقه قرار دارد، آنجا دو بار شمرده میشود. |
کشف و پروتکلهای دیگر
- کارت سرور MCP: /.well-known/mcp/server-card.json (همچنین
/mcp/server-card): نام، نقطهٔ پایانی، ابزارها و نسخهها، بدون نیاز به اتصال. پیکربندی دفتر ثبت:/.well-known/mcp/config-schema.jsonو/.well-known/mcp/examples.json. - فهرست هوش مصنوعی: /.well-known/ai-catalog.json: همهٔ راههای دسترسی (MCP، این API، A2A، NLWeb و مهارت عامل)، همراه با نمونهٔ پرسوجوها.
- فهرست API: /.well-known/api-catalog، مجموعهپیوندی مطابق RFC 9727 که این API، توصیف آن و این مستندات را معرفی میکند.
- مهارت عامل: /.well-known/agent-skills/index.json،
SKILL.mdرا همراه با چکیدهٔ sha256 آن فهرست میکند. - OpenSearch: /opensearch.xml، Edgepedia را بهعنوان ارائهدهندهٔ جستوجو اضافه میکند.
- A2A:
https://www.edgepedia.org/a2a(JSON-RPC؛ A2A 1.0SendMessageو 0.3message/send؛ کارت در/.well-known/agent-card.json). نام یک موضوع، پنج مقالهٔ برتر را برمیگرداند؛ نشانی یک مقاله، متن آن را بهصورت Markdown همراه با عبارت ذکر منبع برمیگرداند. پاسخ همیشه یک پیام است، هرگز یک وظیفه نیست، و همین متدها در/mcpهم پاسخ داده میشوند. - NLWeb:
https://www.edgepedia.org/ask?query=Mount%20Fuji(GET، یا POST با بدنهٔ JSON یا فرم) پاسخ را در قالب فهرست NLWeb میدهد، با یکschema_objectاز schema.org برای هر نتیجه؛streaming=trueفهرست را بهصورت رویدادهای ارسالی از سرور میفرستد. هیچ مدلی فراخوانی نمیشود. - قالبهای ماشینخوان مقاله: نشانی مقاله، پاسخ را در قالبی میدهد که سرآیند
Acceptمشخص میکند:text/markdown(همراه با برآوردx-markdown-tokens)،application/json(پاسخ این API) یاapplication/ld+json؛ هر مقدار دیگری، خود صفحه را برمیگرداند. صفحههای مقاله سرآیندLinkدارند که این قالبها، مجوز، فهرست API و توصیف OpenAPI را معرفی میکند.
فایلهای تولیدشده
این فایلها از روی /openapi.json ساخته میشوند، پس هرگز با آن ناهمخوان نمیشوند.
| فایل | چیست |
|---|---|
| /openapi-3.0.json | همان توصیف در قالب OpenAPI 3.0.3، برای ابزارهایی که نسخهٔ 3.1 را نمیخوانند. |
| /arazzo.json | یک گردش کار Arazzo 1.0: جستوجو، دریافت بهترین تطابق و سپس مقالههای مرتبط با آن. |
| /tools.json | هر مسیر JSON بهصورت تابعی که مدل بتواند آن را فراخوانی کند، در قالبهای OpenAI، Anthropic و Gemini، و نیز بهصورت JSON Schema همراه با مسیرش. |
| /edgepedia.d.ts | نوعهای TypeScript برای همهٔ پاسخها و پارامترهای هر مسیر. |
| /edgepedia.postman_collection.json، /edgepedia.bruno.json، /edgepedia.insomnia.json، /edgepedia.http | برای هر مسیر، یک نمونهٔ درخواست برای Postman، Bruno، Insomnia و VS Code یا JetBrains. |
لطفاً یک User-Agent بفرستید که نام برنامهٔ شما را مشخص کند، همانطور که مجموعهها این کار را میکنند (edgepedia-collection/1).