Edgepedia API
50만 개가 넘는 백과사전 문서를 JSON으로 제공합니다. 문서는 계속 늘어납니다. 무료입니다. 키도, 가입도 필요 없습니다. 출처를 표시하면 상업적으로도 이용할 수 있습니다. AI 학습에는 누구나 사용할 수 있습니다.
사용해 보기
- 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은 문서의 정규 ID로 카드를 제공합니다. 모양은 auto, light, dark 중에서 선택할 수 있습니다. 선택 사항인 /assets/edgepedia-embed.js 스크립트를 사용하면 프레임 크기가 내용에 맞게 조절됩니다. 이 스크립트가 없어도 프레임 안의 내용을 읽고 스크롤할 수 있습니다.
/embed/{slug}도 사용할 수 있습니다. 테마를 유지한 채 해당 문서 ID의 카드로 리디렉션됩니다. 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 | 제목과 다른 이름을 검색하여 일치도가 높은 순으로 반환합니다. 질문이 아니라 대상의 이름으로 검색하세요. 각 결과에는 id, 제목, 최상위 주제, 미리보기 텍스트, 링크, 일치 방식(match, confidence)이 포함됩니다. "science fiction writers"처럼 주제를 가리키는 단어로 검색하면 해당 주제의 문서로 연결되는 링크인 topics도 반환합니다. limit은 페이지당 결과 수로, 1~30입니다(기본값 10). page로 페이지를 넘기며, 마지막 페이지를 지나면 빈 페이지가 반환됩니다. 다른 이름이나 철자가 틀린 이름으로도 검색할 수 있습니다. "zhu yuanzhang"으로 검색하면 홍무제를 찾고, "siddartha"로 검색하면 did_you_mean을 반환합니다. 그 밖의 옵션은 아래의 검색 항목을 참조하세요. |
/api/v1/articles/{slug} | Markdown 형식의 문서, 주제 경로, 지리 트리상의 위치(geo), 최종 갱신일, 표시해야 할 출처 문구를 반환합니다. 어떤 이름이든 사용할 수 있으며(Mount_Fuji, 제목, 전체 주소), 옵션을 지정하면 특정 절, 개요, 구절 또는 다른 형식으로 반환합니다. 아래의 문서 읽기 항목을 참조하세요. |
/api/v1/articles?id={id} | 위와 같은 내용을 id로 조회합니다. 코퍼스 마이그레이션 후에도 이전 문서 id로 계속 조회할 수 있습니다. 주제 id는 트리가 개편되면 바뀔 수 있습니다. 주소가 바뀌더라도 이전 주소는 계속 응답하며, moved_from를 함께 반환합니다. ids=은 한 번에 최대 10개까지 받습니다. |
/api/v1/leads?ids={id},{id} | 카드 목록 페이지에 사용할 수 있도록, id로 지정한 문서를 최대 50개까지 각각 검색 결과 형식(id, 제목, 최상위 주제, 미리보기 텍스트, 링크)으로 반환합니다. 마이그레이션되거나 병합된 id는 요청한 id를 키로 삼아 최종적으로 유지되는 문서를 반환합니다. 결과의 id는 정규 ID입니다. 알 수 없거나 이용할 수 없는 id는 제외됩니다. |
/api/v1/random | 무작위 문서 하나를 반환합니다. new=1은 최신 문서 중에서, topic= 또는 geo=는 특정 노드 아래에서 선택합니다. |
/api/v1/related/{slug} | 한 번의 호출로 문서의 이웃 문서를 반환합니다. 같은 주제에서 가장 가까운 문서 최대 10개, 인접 주제 최대 8개에서 각각 3개, 해당 문서가 속한 각 지리 노드에서 가장 가까운 문서 최대 10개를 제공합니다. ?id={id}도 사용할 수 있습니다. by=links를 지정하면 그 대신 해당 문서와 함께 인용된 문서를 반환합니다. |
/api/v1/topics | 주제 트리의 최상위를 반환합니다. |
/api/v1/topics/{id} | 주제의 경로, 문서 수를 포함한 하위 주제, 해당 주제 아래의 모든 문서를 페이지당 30개씩 반환합니다. format=mermaid는 해당 주제의 하위 트리를 그립니다. |
/api/v1/geo | 지리 트리, 즉 지역과 각 지역의 시대 구분을 반환합니다. |
/api/v1/geo/{id} | 주제와 같은 구조로 지리 노드를 반환합니다. 경로, 더 세분된 노드, 페이지당 30개의 문서로 구성됩니다. 지역 노드에는 시대 구분만 나열됩니다. |
POST /api/v1/ids/translate | v1.5 마이그레이션이 활성화되어 있을 때 사용합니다. {"ids":["old-id", "another-id"]}를 보내세요(중복되지 않는 id 최대 500개). 응답은 변경된 id를 최종적으로 유지되는 정규 ID에 매핑합니다. 변경되지 않았거나 알 수 없는 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를 지정하면 약 4분의 1 더 짧은 텍스트를 반환. topic: id를 지정하면 해당 주제의 상위 주제, 더 세분된 주제, 문서를 page당 120개씩 나열. 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에 집계됩니다. 도구 오류는 모델이 읽는 텍스트로 전달됩니다(어떤 문서에도 해당하지 않는 id에는 did_you_mean id가 포함됩니다). 오류 코드는 _meta["ai.edgechat/error"]에 실리며, structuredContent에는 실리지 않습니다. fetch에 links: "in"를 지정할 때는 links_page를 받아 해당 문서로 링크하는 다음 문서 30개를 가져옵니다.
search는 limit(1~30, 기본값 10), page, first, topic, sort를 받으며, page와 pages를 반환합니다. fetch는 아래의 문서 옵션을 받으며, 여러 문서를 한 번에 가져오려면 ids를 받습니다. 모든 결과에는 문서의 영구 id인 canonical_id가 포함됩니다. fetch에 이 id를 사용할 수 있으며, 저장해 둔 id나 주소가 바뀌었다면 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 형식입니다. /mcp에 GET 요청을 보내면 서버 카드를 JSON으로 반환합니다. text/event-stream만 받는 클라이언트에는 각 응답을 단일 SSE message 이벤트로 보냅니다. 도구 목록의 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)는 본문에 https://www.edgepedia.org/mcp을 안내하는 404 응답을 반환합니다.
제한
API와 MCP 서버 모두 IP 주소당 분당 600회, 일일 100,000회로 요청이 제한됩니다. 모든 응답의 RateLimit-Policy에 두 시간 구간이 모두 표시됩니다. 한도를 초과하면 API는 Retry-After와 RateLimit를 포함한 429 응답을 반환하고, MCP 도구 호출은 retry_after에 초 단위 시간을 담은 도구 오류를 반환합니다. 요청 수는 서버 인스턴스별로 집계되므로, 이 수치는 정확한 계량값이 아니라 넘지 말아야 할 상한선입니다. 캐시를 사용해 주세요. id 변환(POST /api/v1/ids/translate)은 요청한 id마다 별도로 집계합니다. 이전 id를 확인하는 /leads 일괄 요청도 이전 id마다 집계합니다. 그 밖의 일괄 요청은 id 또는 이름 하나당 요청 1회로, annotate는 1,000자당 1회로 집계합니다.
라이선스
Edgepedia 커뮤니티 라이선스 1.0: 출처를 표시하면 상업적 이용을 포함하여 무료로 사용할 수 있습니다. AI 학습에는 누구나 사용할 수 있으며, 모델의 출력에는 출처를 표시하지 않아도 됩니다. 그 밖의 용도로 사용하는 경우, 매출이 미화 1억 달러를 초과하거나 월간 이용자가 1억 명을 초과하는 조직은 별도의 라이선스를 받아야 합니다.
출처 표시: 문서의 텍스트를 표시하는 곳에는 어디든 해당 문서의 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도 포함합니다. MCP fetch 도구의 찾을 수 없음 오류에도 같은 did_you_mean이 포함됩니다.
변경 사항
버전 1은 구조를 유지합니다. 필드가 추가될 수는 있지만, 이름이 바뀌거나 삭제되지는 않습니다. Edgepedia 자체의 변경 사항은 /edgepedia/updates에서 확인할 수 있습니다. 1.8.0처럼 릴리스에서 주제 트리를 재편하면, 이동한 주제 id는 새 id를 포함한 301 응답을 반환하며, /api/v1/changes?since=<release>는 해당 릴리스 이후 추가·변경·이동·삭제된 모든 문서를 나열합니다.
/api/v1은 corpus_version, corpus_updated, release_notes를 반환합니다. 이 값은 공개된 일반 코퍼스 릴리스와 그 릴리스 날짜를 나타내며, 각 문서의 최종 편집일을 나타내는 것은 아닙니다. 같은 메타데이터가 MCP 서버 지침에도 표시됩니다. 코퍼스가 릴리스되어도 API나 MCP 소프트웨어 버전은 바뀌지 않습니다. 그곳의 id_policy는 id가 무엇을 보장하는지 설명합니다. 1.5에서 그랬듯 릴리스에 따라 id가 재부여되거나 병합될 수 있으며, 이전 id는 308과 POST /api/v1/ids/translate을 통해 계속 응답합니다.
문제가 있나요? 신고해 주세요.
참조
파생 데이터(중요도, 읽기 수준, 링크, 날짜, 다른 이름, 전문 검색 색인)를 읽는 경로와 필드는 해당 데이터가 저장소와 함께 공개될 때까지 Retry-After를 포함한 503 응답을 반환하거나 해당 필드를 생략합니다.
문서 읽기
/api/v1/articles/{slug}과 MCP fetch은 다음 옵션을 받습니다. 옵션이 없으면 문서 전체를 반환합니다.
| 옵션 | 반환 내용 |
|---|---|
section={heading} | 절 제목 또는 그 제목에 포함된 단어로 지정한 절 하나를 하위 절과 함께 반환합니다(section=etymology는 "이름과 어원"을 찾으며, section=lead는 도입부입니다). 알 수 없는 절 제목이면 문서의 sections를 포함한 404 응답을 반환합니다. |
outline=1 | outline: 모든 제목과 각 부분의 토큰 수를 반환합니다. |
max_tokens={n} | 절 또는 문단 경계에서 약 n개 토큰으로 잘라 낸 텍스트를 tokens_estimate, truncated, next_cursor과 함께 반환합니다. 나머지를 받으려면 같은 max_tokens을 사용하고 이를 cursor로 전달하세요. |
length=snippet, length=lead | 전문 대신 발췌문 또는 제목과 첫 문단을 반환합니다. |
format=text, html, jsonld, turtle, tables | 응답을 일반 텍스트, 렌더링된 본문 또는 공개 필드의 JSON-LD나 Turtle 형식으로 반환합니다. tables는 각 표를 columns와 rows로, 그리고 csv로 제공하며, 표의 인용은 cites과 sources로 옮깁니다. |
chunks=1 | chunks: 문서를 문단별로 반환합니다. 각 문단에는 제목 경로(geology-2)에서 생성한 고정 id와 cite_url이 포함됩니다. |
q={words}&k={1–10} | passages: 주어진 단어와 가장 잘 일치하는 문단 k개(기본값 3)를 각각 cite_url과 함께 반환합니다. |
quote={sentence or chunk id} | cite_url: 페이지의 해당 구절을 바로 여는 텍스트 프래그먼트가 붙은 문서 주소를 반환합니다. quote_found는 문서에 그 구절이 있는지 알려 줍니다. |
cite={format} | cite: /api/v1/cite와 같은 방식으로 문서의 서지 정보를 반환합니다. |
모든 문서 응답에는 speakable(음성 비서가 읽을 수 있는 형태의 발췌문)도 포함됩니다. importance과 rank(문서 간 링크에 대한 PageRank. 1이 가장 중심에 있으며, 대상에 대한 평가가 아니라 링크 수에 따른 값), words, reading_grade(플레시-킨케이드), reading_minutes은 fields=에 지정한 경우에만 포함됩니다(?fields=title,importance,rank). MCP fetch에는 항상 포함됩니다. next=1는 다음에 읽을 문서를 최대 5개 추가합니다. citations=false는 MCP의 citations: false와 마찬가지로 markdown, chunks, passages의 본문 내 출처 링크를 [n] 표시로 바꿉니다. 어떤 문서에도 해당하지 않는 주소는 문서 id(/api/v1/articles/ep7rbwcy0a) 또는 제목으로 해석하며, 대소문자와 악센트는 구분하지 않습니다(/api/v1/articles/paris). 소문자와 하이픈으로 된 주소가 이 기준으로도 일치하지 않으면 ?suggest=1을 추가하지 않는 한 404 응답을 반환합니다. 반면 대문자, 공백, 밑줄이 있는 주소(/api/v1/articles/Albert_Einstein)는 이름으로 해석하므로, 비슷하게 입력하면 가장 일치하는 검색 결과를 resolved_by: search과 함께 반환합니다. 입력한 이름이 해당 문서의 주소가 아니면, 응답에는 이를 어떻게 해석했는지(resolved_from, resolved_by: 주소, 제목 또는 검색)가 표시되며 다른 문서 3개가 nearest으로 나열됩니다. /api/v1/articles?ids={slug or id},{name}는 최대 10개를 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}은 한 번에 최대 50개까지 같은 방식으로 제공합니다. 저자는 Edgepedia(EdgeChat)입니다. APA, MLA, 시카고, 하버드 양식에서는 Markdown처럼 별표로 제목의 이탤릭체를 표시합니다. 참고 카드에도 서지 관리 프로그램을 위해 같은 인용 정보가 COinS와 JSON-LD 형식으로 보이지 않게 포함됩니다.
검색
match | 조건 | confidence |
|---|---|---|
exact | 제목이 검색어와 같습니다. | 이런 결과 중 첫 번째는 1.0, 그다음부터는 0.9 |
alias | 다른 이름이나 제목의 머리글자("mlk")가 일치합니다. | 0.8. 검색어의 단어가 하나도 없는 첫 번째 결과는 0.7, 로마자로 변환한 검색어는 0.6 |
misspelling | 검색 과정에서 검색어를 교정했습니다(did_you_mean). | 0.5 × 교정 후에도 유지된 원래 검색어의 비율 |
partial | 검색어의 일부 단어가 제목에 있거나, 본문에만 있습니다. | 0.2 + 0.5 × 검색어의 단어 중 제목에 있는 비율. 본문에만 있으면 0.2 |
fulltext | 일치하는 제목이나 다른 이름이 없어 문서 본문을 검색했습니다(BM25). 이름을 몰라도 설명으로 문서를 찾을 수 있습니다. | 0.2 이상 |
none | 일치하는 결과가 없습니다. 응답은 비어 있습니다. | 0 |
신뢰도는 보정된 확률이 아니라 정해진 규칙에 따른 값입니다. 가장 높은 결과의 점수가 0.2 미만이면 빈 응답을 반환합니다. 각 결과에는 요약에서 검색어의 단어가 가장 많이 들어 있는 문장인 highlight이 포함됩니다. 결과가 없으면 로마자로 바꾸어 한 번 더 검색하고(키릴 문자, 그리스 문자, 가나, 한글을 로마자로 변환하고, 병음의 성조 숫자를 없애며, 일본어 로마자 표기의 중복 모음을 하나로 줄임), 응답에 이를 searched_as로 표시합니다. 한자는 로마자로 변환하지 않습니다.
| 옵션 | 기능 |
|---|---|
first=true | 가장 일치하는 결과 하나만 반환하거나, 아무것도 반환하지 않습니다. |
topic={id}, geo={id} | 해당 주제 또는 지리 노드 아래의 문서만 반환합니다. geo는 최대 1,000개의 일치 결과 전체에 필터를 적용하며, scope은 응답이 어디까지 다루는지 나타냅니다. |
sort=central | 최대 1,000개의 일치 결과 전체에서 링크가 가장 많이 연결된 대상을 먼저 반환합니다. |
max_grade={grade} | 읽기 수준이 해당 학년 이하인 문서만 반환합니다. |
facets=1 | 최대 1,000개의 일치 결과 전체에 대해 최상위 주제별, 지리적 지역별 결과 수를 반환합니다(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=를 비워 두면 처음부터 시작하며, 삭제된 id를 포함해 어떤 id 뒤에서든 순회를 이어 갈 수 있습니다. |
/api/v1/trees, /api/v1/trees/topic, /api/v1/trees/geo | 주제 트리와 지리 트리 전체를 반환합니다. nodes: [[id, label, parent index, own articles]]. 점으로 시작하는 id는 상위 노드의 id 뒤에 이어 붙입니다. |
/api/v1/releases | 최신순으로 정렬한 코퍼스 릴리스와 current을 반환합니다. |
/api/v1/health | application/health+json: pass, warn 또는 fail(503)를 반환합니다. |
/api/v1/manifest | 문서 하나가 한 줄을 차지하는 gzip 압축 JSONL 파일 하나로 리디렉션합니다. { id, slug, title, updated, sha256, topic }(문서의 .md에 대한 sha256). 한 번 내려받으면 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 }, 그리고 YYYY, YYYY-MM 또는 YYYY-MM-DD 형식의 date으로 구성됩니다(기원전은 음수: -0044-03-15). 기원전 날짜는 천문학적 연도가 아니라 역사학의 관례를 따릅니다. -0044는 기원전 44년입니다(표준 ISO 8601 파서는 이를 기원전 45년으로 해석합니다). 근거는 문장 자체입니다. 날짜를 사실로 받아들이기 전에 문장을 읽어 보세요. |
/api/v1/aliases/{id} | 문서에 명시된 두문자어("NASA")를 포함하여 문서의 다른 이름을 반환합니다. 오탈자나 대소문자만 다른 형태는 제외하며, 같은 이름의 두 표기 중에서는 마침표가 없는 것을 남깁니다("W.H.O."가 아니라 "WHO"). |
이름 식별, 주석 달기, 데이터 대조
자유 형식 텍스트를 입력하면 모델이나 임베딩 없이 문서 id를 반환합니다. annotate, classify, geoparse로 보낸 텍스트는 로그에 남기거나 보관하지 않습니다.
| 경로 | 반환 내용 |
|---|---|
/api/v1/resolve?name=Mercury&context=planet | 주어진 이름이 가리킬 가능성이 가장 높은 문서를 반환합니다. result, confidence, ambiguous, match(exact, alias, anchor, partial 또는 none), alternatives로 구성됩니다. type=는 특정 주제 id 아래의 후보만 남깁니다(이름 하나를 조회할 때 처음 30개 결과에 해당 주제의 문서가 없으면 다음 60개까지 살펴봅니다). limit=은 1~10입니다. POST는 최대 50개를 받습니다. { "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": "…" }(최대 20,000자): 링크가 연결된 각 구절과 그 위치(start, end. JavaScript의 문자열 인덱스와 같은 UTF-16 코드 단위이므로, 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 | Reconciliation Service API 0.2 엔드포인트입니다. 매니페스트, 일괄 queries(GET 또는 POST), 엔터티·유형·속성 제안, 미리보기, 데이터 확장(title, url, excerpt, topic, topic_path, importance_rank)을 제공합니다. callback=를 지정하면 JSONP를 사용합니다. 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= | 해당 문서로 링크하는 문서를 중요도가 높은 순으로 페이지당 30개씩 반환하며, 앵커 텍스트도 함께 제공합니다. |
/api/v1/path?from=&to= | 두 문서 사이의 가장 짧은 링크 연결 경로(최대 6단계, 가능한 한 허브를 피함)를 각 단계를 연결하는 문장과 함께 반환합니다. MCP 서버에서는 이를 connect이라고 합니다. |
/api/v1/compare?a=&b= | 두 문서를 나란히 비교합니다. 도입부, 주제 경로, 두 문서가 공유하는 가장 깊은 주제, 둘 사이의 연결 경로, 공통 링크와 각 문서에만 있는 링크, 각 문서의 핵심 정보 표를 반환합니다. |
/api/v1/graph/{slug}?depth=1|2&limit= | 가장 중요한 이웃 문서를 limit개까지(기본값 50, 최대 200), 그리고 그 문서 사이의 모든 링크를 반환합니다. complete: false는 이 경로와 backlinks, rank/top에서 약 1초인 경로의 처리 시간 한도로 인해 응답이 잘렸음을 뜻합니다. 이런 응답은 1분 동안만 캐시됩니다. |
POST /api/v1/context | { "ids": [...] }, 최대 50개의 id 또는 주소(/rank?ids=과 /leads?ids=도 같은 입력을 받음): 이들 사이의 링크, 이들 대부분과 링크로 연결된 문서, 이들이 공유하는 가장 깊은 주제와 장소, 각 문서의 도입부를 반환합니다. |
/api/v1/rank?ids=, /api/v1/rank/top?topic=&limit= | PageRank에 따른 중요도를 반환합니다. pr은 코퍼스 전체의 합이 1이며, 순위 1이 가장 중심에 있습니다. 필드 이름에 유의하세요. /search와 문서의 importance은 이 순위를 0~1의 백분위 값으로 나타낸 것입니다. /resolve의 importance은 가공하지 않은 pr이며, /leads의 값은 { pr, rank }입니다. |
/api/v1/timeline?topic=|geo=&from=&to= | 특정 주제나 장소에 속하는 문서에서 날짜가 있는 문장을 오래된 순으로 페이지당 50개씩 반환합니다. 기원전 연도는 음수입니다. 노드마다 전체 날짜 범위에 걸쳐 분포하도록 최대 200개의 사건을 남기며, from과 to은 이 표본을 필터링합니다. 표본이 최대 개수에 도달한 상태에서 가져온 응답에는 sampled: true과 해당 cap이 표시되며, total는 표본의 수를 셉니다. |
/api/v1/onthisday?date=MM-DD, /api/v1/year/{year} | 연중 특정 날짜(기본값은 UTC 기준 오늘) 또는 특정 연도(-9999~2100)의 사건을 반환합니다. 날짜 하나에는 최대 500개, 연도 하나에는 최대 2,000개의 사건이 포함됩니다. 최대 개수에 도달하면 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)에 속하는 문서를 페이지당 30개씩 반환합니다. 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. - AI 카탈로그: /.well-known/ai-catalog.json. 모든 접근 방식(MCP, 이 API, A2A, NLWeb, 에이전트 스킬)과 예시 질의를 제공합니다.
- API 카탈로그: /.well-known/api-catalog. 이 API와 그 명세, 이 문서를 가리키는 RFC 9727 링크 집합입니다.
- 에이전트 스킬: /.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에서 제공). 대상의 이름을 입력하면 상위 문서 5개를 반환하고, 문서 주소를 입력하면 출처 문구가 포함된 Markdown 문서를 반환합니다. 응답은 항상 메시지이며 작업 형태로 반환하지 않습니다./mcp에서도 같은 메서드에 응답합니다. - NLWeb:
https://www.edgepedia.org/ask?query=Mount%20Fuji(GET 또는 JSON이나 폼 본문을 담은 POST)는 NLWeb의 목록 형식으로 응답하며, 각 결과는 schema.org의schema_object입니다.streaming=true은 목록을 서버 전송 이벤트로 보냅니다. 모델은 호출하지 않습니다. - 기계 처리용 문서 형식: 문서 주소는
Accept헤더에 지정한 형식으로 응답합니다.text/markdown(x-markdown-tokens추정값 포함),application/json(이 API의 응답),application/ld+json중 하나이며, 그 밖의 경우에는 페이지를 반환합니다. 문서 페이지에는 이 형식들과 라이선스, API 카탈로그, OpenAPI 명세를 가리키는Link헤더가 포함됩니다.
생성 파일
/openapi.json에서 생성하므로, 언제나 원본과 일치합니다.
| 파일 | 내용 |
|---|---|
| /openapi-3.0.json | 3.1을 읽지 못하는 도구를 위해 같은 명세를 OpenAPI 3.0.3으로 제공합니다. |
| /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).