API와 기계 판독 안내
TapeFlow가 공개하는 지표 히스토리 JSON API, OpenAPI 명세, RFC 9727 API 카탈로그, 마크다운 표현, 인증 정책을 사람과 자동화 에이전트가 모두 확인할 수 있도록 한곳에 정리한 문서입니다.
인증
없음
가입, 키 발급, 토큰 교환 절차가 존재하지 않습니다.
응답 형식
JSON
OpenAPI 3.1 명세로 스키마를 기술합니다.
갱신 방식
정적 빌드
요청 시점이 아니라 사이트 재빌드 시점에 값이 바뀝니다.
핵심 요약
- 지표 히스토리는 인증 없이 GET 한 번으로 받을 수 있는 읽기 전용 JSON 엔드포인트로 공개됩니다.
- 기계 판독 진입점은 /.well-known/api-catalog(RFC 9727)이며, 모든 페이지 응답의 Link 헤더가 이 카탈로그를 가리킵니다.
- 계정, 발급 키, OAuth 인증 서버가 없으므로 어떤 자격 증명도 보낼 필요가 없고 보내서도 안 됩니다.
공개 검토 경로
TapeFlow의 공개 가치는 법적 문서 하나가 아니라 지표, 레이더, 방법론, 출처 고지가 서로 연결될 때 드러납니다. 아래 경로는 사용자가 숫자의 원천과 해석 기준을 직접 따라갈 수 있게 합니다.
지표 히스토리 엔드포인트
GET https://caelion.dev/api/indicators/{slug}/history 는 해당 지표의 저장된 전체 관측치를 오래된 순서대로 반환합니다. slug는 지표 상세 페이지 주소에 쓰이는 식별자와 같습니다. 예를 들어 KOSPI 지수는 kospi_index 입니다.
응답 본문에는 관측 시작일(historyStartDate), 관측 종료일(historyEndDate), 관측치 수(historyPointCount), 그리고 날짜와 값이 담긴 rows 배열이 들어갑니다. 원천이 시가·고가·저가·종가·거래량을 제공하는 지표에서는 각 행에 해당 필드가 함께 채워집니다.
주소 끝에 슬래시를 붙이면 슬래시 없는 정규 주소로 301 이동합니다. 존재하지 않는 slug는 HTML 오류 페이지가 아니라 JSON 오류 본문과 함께 404를 반환합니다.
- 예시 요청: https://caelion.dev/api/indicators/kospi_index/history
- 사용 가능한 slug 목록은 지표 목록 페이지와 sitemap.xml에서 확인할 수 있습니다.
- 일부 지표는 공개 상세 페이지가 없으며, 그런 지표에는 히스토리 엔드포인트도 제공되지 않습니다.
자동화 에이전트를 위한 발견 경로
기계 판독 진입점은 RFC 9727이 정한 위치인 https://caelion.dev/.well-known/api-catalog 입니다. 이 문서는 application/linkset+json 형식이며, API를 설명하는 OpenAPI 명세(service-desc), 사람이 읽는 문서(service-doc), 이용 조건과 인증 정책(service-meta) 링크를 함께 담습니다.
사이트의 모든 페이지 응답에는 RFC 8288 Link 헤더가 붙어 카탈로그, OpenAPI 명세, 이 문서, 그리고 해당 페이지의 마크다운 표현을 가리킵니다. 따라서 첫 요청 한 번으로 기계 판독 자원 전체를 찾아갈 수 있습니다.
- API 카탈로그: https://caelion.dev/.well-known/api-catalog
- OpenAPI 3.1 명세: https://caelion.dev/api/openapi.json
- 인증 정책 문서: https://caelion.dev/auth.md
- 수집 정책과 콘텐츠 시그널: https://caelion.dev/robots.txt
인증과 자격 증명
TapeFlow에는 로그인, 회원 계정, 발급 키, OAuth 인증 서버가 없습니다. 모든 자원은 익명 GET으로 열려 있으므로 Authorization 헤더나 API 키를 보낼 이유가 없고, 발급한 적 없는 자격 증명을 이 도메인으로 보내면 유출 위험만 생깁니다.
그래서 OAuth 보호 자원 메타데이터나 인증 서버 메타데이터도 일부러 게시하지 않습니다. 운영하지 않는 인증 체계를 광고하면 에이전트가 존재하지 않는 등록 절차를 시도하게 되기 때문입니다. 자세한 내용은 auth.md 문서에 정리되어 있습니다.
자격 증명 대신 User-Agent 헤더에 이름과 연락 가능한 주소를 남겨 주세요. 의무는 아니지만 트래픽 문제를 확인해야 할 때 정상적인 클라이언트를 구분하는 유일한 단서가 됩니다.
마크다운 표현
모든 페이지에는 마크다운 표현이 함께 배포됩니다. 요청에 Accept: text/markdown 을 넣거나 주소 끝에 .md 를 붙이면 본문만 담긴 텍스트를 받을 수 있고, 응답의 x-markdown-tokens 헤더에 대략적인 토큰 수가 표시됩니다.
브라우저처럼 text/html 을 우선하거나 Accept 를 보내지 않는 요청은 그대로 HTML을 받습니다. 같은 주소가 두 표현을 제공하므로 응답에는 Vary: Accept 가 붙습니다.
- 예시: curl -H "Accept: text/markdown" https://caelion.dev/ko/indicators/kospi_index/
- 예시: https://caelion.dev/ko/indicators/kospi_index.md
이용 조건과 한계
이 API는 정적 배포물입니다. 값은 요청 시점이 아니라 사이트가 다시 빌드될 때 갱신되므로 실시간 시세 용도로는 적합하지 않습니다. 매매 판단에는 반드시 거래 중개사의 실시간 데이터를 사용해야 합니다.
발표된 속도 제한은 없지만 모든 지표를 동시에 반복 수집하는 방식은 피해 주세요. 지표 값은 제3자 공개 원천에서 파생된 자료이므로 재배포 조건은 각 원천 제공처의 라이선스를 따릅니다. robots.txt의 콘텐츠 시그널은 운영자의 선호를 밝히는 선언이며 접근 통제 장치가 아닙니다.
엔드포인트 구조나 응답 필드는 사전 공지 없이 바뀔 수 있습니다. 자동화 클라이언트는 OpenAPI 명세를 기준으로 삼고, 알 수 없는 필드가 늘어나도 깨지지 않도록 작성하는 편이 안전합니다.