Our.
External API

OurDots API

게시 완료 상태이고 외부 전송이 허용된 강의, 공개 댓글, 강사 프로필을 조회합니다. 이름은 기본적으로 비식별 처리됩니다.

Lecture list

강의 목록

GET/api/v1/external/lectures

scope ourdots.lectures

PUBLISHED 상태이면서 apiExportEnabled=true인 강의만 최신 발행순으로 반환합니다.

파라미터

  • page — 1 이상 정수, 기본값 1
  • pageSize — 1 이상 100 이하 정수, 기본값 20. size 별칭도 허용

cURL

curl -sS "https://our.co.kr/api/v1/external/lectures?page=1&pageSize=20" \
  -H "Authorization: Bearer od_xxxx.{secret}"

응답 예시

{
  "lectures": [
    {
      "id": "lec_od_xxxx",
      "title": "작은 시작이 변화를 만드는 법",
      "summary": "현장에서 배운 실행 루틴을 공유합니다.",
      "lectureType": "STORY",
      "trackMapping": "impact-basic",
      "durationSec": 842,
      "publishedAt": "2026-07-01T03:00:00.000Z",
      "thumbnailUrl": "https://our.co.kr/api/files/thumbs%2Flec_od_xxxx.jpg",
      "creator": {
        "id": "usr_od_xxxx",
        "name": "홍*동",
        "affiliation": "Our Dots Lab"
      },
      "categories": ["startup"],
      "themes": ["execution", "impact"]
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 1,
  "totalPages": 1
}

오류

  • 400 INVALID_QUERY — page 또는 pageSize 조건 오류
  • 401 UNAUTHORIZED — credential 누락 또는 불일치
  • 403 FORBIDDEN — ourdots.lectures scope 없음
  • 429 RATE_LIMITED — IP 기준 120 req/min 초과
Lecture detail

강의 상세

GET/api/v1/external/lectures/{id}

scope ourdots.lectures

강의 본문 메타데이터와 시청용 URL을 반환합니다. streamUrl, vttUrl, localizations[].dubVideoUrl은 600초 뒤 만료되는 서명 URL입니다.

파라미터

  • id — 강의 ID

cURL

curl -sS "https://our.co.kr/api/v1/external/lectures/lec_od_xxxx" \
  -H "Authorization: Bearer od_xxxx.{secret}"

응답 예시

{
  "id": "lec_od_xxxx",
  "title": "작은 시작이 변화를 만드는 법",
  "summary": "현장에서 배운 실행 루틴을 공유합니다.",
  "lectureType": "STORY",
  "trackMapping": "impact-basic",
  "durationSec": 842,
  "publishedAt": "2026-07-01T03:00:00.000Z",
  "thumbnailUrl": "https://our.co.kr/api/files/thumbs%2Flec_od_xxxx.jpg",
  "streamUrl": "https://media.example.invalid/lec_od_xxxx.mp4?expires=600",
  "vttUrl": "https://media.example.invalid/lec_od_xxxx.vtt?expires=600",
  "chapters": [
    { "startMs": 0, "title": "문제 정의" },
    { "startMs": 245000, "title": "실행 루틴" }
  ],
  "creator": {
    "id": "usr_od_xxxx",
    "name": "홍*동",
    "affiliation": "Our Dots Lab",
    "jobTitle": "프로젝트 리드",
    "verified": true
  },
  "categories": ["startup"],
  "themes": ["execution", "impact"],
  "localizations": [
    {
      "locale": "en",
      "translatedTitle": "How Small Starts Create Change",
      "subtitleReady": true,
      "subtitleVttUrl": "https://our.co.kr/api/files/l10n%2Flec_od_xxxx.en.vtt",
      "dubReady": true,
      "dubVideoUrl": "https://media.example.invalid/lec_od_xxxx.en.mp4?expires=600"
    }
  ]
}

오류

  • 401 UNAUTHORIZED — credential 누락 또는 불일치
  • 403 FORBIDDEN — ourdots.lectures scope 없음
  • 404 LECTURE_NOT_FOUND — 외부 전송 허용 강의 없음
  • 404 RENDER_NOT_FOUND — 시청 가능한 영상 준비 전
  • 429 RATE_LIMITED — IP 기준 120 req/min 초과
Comments

댓글·질문

GET/api/v1/external/lectures/{id}/comments

scope ourdots.comments

공개 reflection과 질문/답글을 최근순으로 최대 100개씩 반환합니다. 답글은 질문 안에서 작성순입니다.

파라미터

  • id — 강의 ID

cURL

curl -sS "https://our.co.kr/api/v1/external/lectures/lec_od_xxxx/comments" \
  -H "Authorization: Bearer od_xxxx.{secret}"

응답 예시

{
  "lectureId": "lec_od_xxxx",
  "reflections": [
    {
      "id": "ref_od_xxxx",
      "body": "이번 주 팀 회의에 바로 적용해 보겠습니다.",
      "createdAt": "2026-07-02T09:00:00.000Z",
      "author": { "name": "박*수" }
    }
  ],
  "questions": [
    {
      "id": "q_od_xxxx",
      "body": "첫 인터뷰 질문은 몇 개가 적당한가요?",
      "createdAt": "2026-07-02T09:10:00.000Z",
      "author": { "name": "홍*동" },
      "replies": [
        {
          "id": "reply_od_xxxx",
          "body": "세 가지 핵심 질문만 남겨도 충분합니다.",
          "stamp": 245,
          "createdAt": "2026-07-02T09:20:00.000Z",
          "author": { "name": "김*영" }
        }
      ]
    }
  ]
}

오류

  • 401 UNAUTHORIZED — credential 누락 또는 불일치
  • 403 FORBIDDEN — ourdots.comments scope 없음
  • 404 LECTURE_NOT_FOUND — 외부 전송 허용 강의 없음
  • 429 RATE_LIMITED — IP 기준 120 req/min 초과
Creator

강사 정보

GET/api/v1/external/creators/{id}

scope ourdots.creators

외부 전송 가능한 게시 강의가 있는 강사의 공개 프로필을 반환합니다. 이메일과 전화번호는 PII 허용 키에도 반환하지 않습니다.

파라미터

  • id — 강사 사용자 ID

cURL

curl -sS "https://our.co.kr/api/v1/external/creators/usr_od_xxxx" \
  -H "Authorization: Bearer od_xxxx.{secret}"

응답 예시

{
  "id": "usr_od_xxxx",
  "name": "홍*동",
  "affiliation": "Our Dots Lab",
  "jobTitle": "프로젝트 리드",
  "education": "사회혁신 석사",
  "career": "지역 프로젝트 운영 8년",
  "certifications": "퍼실리테이터 인증",
  "portfolioUrl": "https://example.invalid/portfolio/od_xxxx",
  "verified": true
}

오류

  • 401 UNAUTHORIZED — credential 누락 또는 불일치
  • 403 FORBIDDEN — ourdots.creators scope 없음
  • 404 CREATOR_NOT_FOUND — 외부 전송 가능한 강사 없음
  • 429 RATE_LIMITED — IP 기준 120 req/min 초과

계약 버전·변경 이력

v1 · 2026-07-07 기준. 이 페이지는 docs/api-contracts/external/*의 계약 문서와 실제 apps/web/app/api/v1/external/* route 구현을 함께 기준으로 작성했습니다.

참조 SSOT: docs/api-contracts/external/auth.mddocs/api-contracts/external/ourdots.md