Content API

설정 예상 시간: 10분

독자가 블로그를 열면 웹사이트 서버가 Surpasso에서 공개 글을 불러옵니다. 기존 블로그 관리 화면에 글 자체를 저장하려면 Webhook을 사용하세요.

준비

웹사이트 AI 개발 도구 또는 유지보수 담당자.
호스팅 설정 변경 권한.

웹사이트 도구에 안내 전달

기존 디자인, 글, 링크를 유지하면서 Surpasso 글을 추가하도록 아래 안내를 복사합니다.

연결 안내 보기

Surpasso는 기업이 SEO 및 GEO 글을 기획하고 작성해 게시하도록 돕는 제품입니다. 기존 웹사이트를 Surpasso에 연결하세요. 먼저 프레임워크, 블로그 경로, 글 저장 방식, 디자인, 배포 방식을 확인하고 기존 기능을 우선 재사용합니다. 사이트를 다시 만들거나 기존 글을 삭제 또는 덮어쓰지 마세요.

Content API을 사용합니다. 웹사이트 서버에서 Surpasso의 게시된 글을 읽습니다. 글은 Surpasso에서 관리되며 로컬 CMS로 자동 복사되지 않습니다. 서버 환경 변수: SURPASSO_URL=https://surpasso.ai, SURPASSO_CONTENT_API_KEY=<배포 설정에서 안전하게 구성>. 서버 키로 Authorization: Bearer를 전송하고 NEXT_PUBLIC_은 절대 사용하지 마세요.

실제 엔드포인트: GET /api/content/v1/articles?limit=50은 {items:[article],nextCursor}를 반환합니다. nextCursor가 있으면 cursor 매개변수로 다음 페이지를 가져옵니다. GET /api/content/v1/articles/{id-or-slug}는 {item:article}을 반환합니다. updated_since로 업데이트를 필터링할 수 있습니다. 게시된 글만 읽을 수 있습니다. 빈 목록은 연결 실패가 아니며 테스트를 위해 초안을 자동 게시하지 마세요. 401, 404, 429(Retry-After 준수), 일시 오류를 처리합니다. ETag / If-None-Match와 304를 지원하고 304 응답을 JSON으로 파싱하지 마세요.

필드 매핑: id = 안정적인 글 식별자, revision = 콘텐츠 버전, title = 제목, slug = 글 경로, excerpt = 요약, contentMarkdown / contentHtml = 본문(기존 편집기에 맞는 형식을 사용하고 HTML을 안전하게 처리), metaTitle / metaDescription = SEO 메타데이터, featuredImage.url / alt = 대표 이미지와 대체 텍스트, images = 본문 이미지, author / authorType / authorUrl = 작성자, editor / reviewer 및 각 Type / Url = 편집 정보, categories / tags = 분류, language = 콘텐츠 언어, contentFamilyId / alternates = 다국어 관계와 링크, structuredData = 구조화 데이터, canonicalUrl = 표준 URL. 최종 URL에는 웹사이트의 실제 공개 경로를 사용하고 잘못된 canonical을 복사하지 마세요. null을 안전하게 처리하고 지원하지 않는 선택 필드가 게시를 막지 않게 하세요.

글에는 날짜 표시와 캐시 갱신을 위한 publishedAt, updatedAt도 포함됩니다. 기존 블로그 경로를 재사용하고 목록, 상세, 안전한 본문 렌더링, SEO, canonical, Open Graph, 언어 링크, Sitemap을 보완합니다. 기존 글과 URL을 유지하세요. 성공한 읽기 결과를 캐시하고 일시 장애 시 가능한 경우 캐시를 표시하며 업데이트 반영 지연을 설명합니다.

필요한 검사를 실행한 뒤 일반 사용자가 이해할 수 있게 변경 기능, 배포 단계, 설정할 환경 변수 이름과 배포 대시보드, Surpasso에 다시 입력할 URL, 글 게시와 업데이트 확인 방법을 설명하세요. 비밀 값은 웹사이트 배포 플랫폼의 환경 변수에서 설정하도록 안내하고 채팅, Git, 브라우저 코드에는 절대 넣지 마세요.

키와 환경 변수 설정

Integrations → Custom → Content API에서 키를 만들고 한 번 표시될 때 저장합니다. 호스팅에 SURPASSO_URL=https://surpasso.ai와 SURPASSO_CONTENT_API_KEY=<키>를 추가하고 재배포합니다. 글 링크가 자사 도메인을 사용하는지도 확인합니다.

글과 읽기 활동 확인

Content Calendar에서 글을 발행하고 블로그의 본문, 이미지, 링크를 확인합니다. 연결 화면에서 읽기 활동 확인을 선택하고 실제 페이지도 직접 검토하세요. Surpasso에서 수정·재발행한 뒤 캐시가 갱신되면 같은 페이지가 바뀌는지 확인합니다.

공개 글만 표시되고 초안은 비공개입니다. Content API는 사이트 자체 블로그 관리 화면에 글을 추가하지 않습니다.

글이 없거나 오류 또는 수정 지연

글 공개, 이 사이트용 키, 환경 변수 저장, 재배포를 확인합니다. 빈 목록은 일치하는 공개 글 없음, 401은 키 문제이며 누락 글은 사이트 링크가 잘못되었을 수 있습니다. 캐시 때문에 늦다면 사이트 도구에 갱신 주기를 확인하세요.

키 분실 또는 노출

연결에서 키를 교체하고 호스팅의 SURPASSO_CONTENT_API_KEY를 업데이트해 재배포합니다. 기존 키는 작동하지 않고 다시 표시되지 않습니다.

기술 참고: API와 글 필드

서버에서 Authorization: Bearer <server-side-key>를 보냅니다. GET /api/content/v1/articles?limit=50은 목록, GET /api/content/v1/articles/{id-or-slug}는 한 글을 반환합니다. limit은 1~50, nextCursor를 cursor로 전달하고 updated_since로 업데이트를 필터링합니다. ETag/If-None-Match와 304를 처리하며 빈 304 본문을 JSON으로 읽지 마세요. 연결당 분당 600회이고 429의 Retry-After, 401, 404, 일시 장애를 구분합니다.

글에는 ID와 revision, 제목, slug, 요약, Markdown/HTML, SEO, 이미지, 편집 크레딧, 카테고리, 태그, 언어·번역 관계, 구조화 데이터, 날짜가 있습니다. 선택값은 null일 수 있습니다. 성공 응답을 캐시하고 장애 시 서버 키를 노출하지 마세요.