openapi: 3.0.3
info:
  title: Teachable Admin Courses API
  description: 'REST API for managing Teachable school data including courses, users, enrollments, quiz responses, pricing plans, transactions, and webhooks. Authenticated via API key header and available on Growth plan and above.

    '
  version: '1'
  contact:
    name: Teachable Support
    url: https://support.teachable.com
    email: support@teachable.com
  termsOfService: https://teachable.com/terms-of-use
servers:
- url: https://developers.teachable.com/v1
  description: Teachable Admin API
security:
- ApiKeyAuth: []
tags:
- name: Courses
  description: Course management endpoints
paths:
  /courses:
    get:
      operationId: listCourses
      summary: List all courses
      description: Fetch all courses at your school.
      tags:
      - Courses
      parameters:
      - name: name
        in: query
        description: Filter courses by course name.
        schema:
          type: string
      - name: is_published
        in: query
        description: Filter courses by published status.
        schema:
          type: boolean
      - name: author_bio_id
        in: query
        description: Filter courses by a specific course author via the course author's bio ID.
        schema:
          type: integer
          format: int32
      - name: created_at
        in: query
        description: Return courses by the date & time of course creation. Formatted in ISO8601.
        schema:
          type: string
          format: date-time
      - name: page
        in: query
        description: Used in pagination when number of courses exceed the maximum amount of results per page.
        schema:
          type: integer
          format: int32
      - name: per
        in: query
        description: Used in pagination to define amount of courses per page, when not defined the maximum is 20.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoursesListResponse'
  /courses/{course_id}:
    get:
      operationId: getCourse
      summary: Get a course
      description: Return a course by its unique ID.
      tags:
      - Courses
      parameters:
      - name: course_id
        in: path
        required: true
        description: Return a course by its unique ID.
        schema:
          type: integer
          format: int32
          minimum: 1
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CourseDetailResponse'
        '404':
          description: Course not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /courses/{course_id}/progress:
    get:
      operationId: getCourseProgress
      summary: Get course progress
      description: Return the progress of a user in a specific course.
      tags:
      - Courses
      parameters:
      - name: course_id
        in: path
        required: true
        description: The unique course ID that contains the lecture.
        schema:
          type: integer
          format: int32
          minimum: 1
      - name: user_id
        in: query
        required: true
        description: The unique ID of the user.
        schema:
          type: integer
          format: int32
      - name: page
        in: query
        description: Used in pagination when number of courses exceed the maximum amount of results per page.
        schema:
          type: integer
          format: int32
      - name: per
        in: query
        description: Used in pagination to define amount of courses per page, when not defined the maximum is 20.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CourseProgressResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /current_user/courses:
    get:
      operationId: listCurrentUserCourses
      summary: List current user courses
      description: Fetch all courses for the current authenticated user.
      tags:
      - Courses
      security:
      - OAuth2:
        - courses:read
      - AccessToken: []
      parameters:
      - name: name
        in: query
        description: Filter courses by course name.
        schema:
          type: string
      - name: is_published
        in: query
        description: Filter courses by published status.
        schema:
          type: boolean
      - name: created_at
        in: query
        description: Return courses by the date & time of course creation. Formatted in ISO8601.
        schema:
          type: string
          format: date-time
      - name: page
        in: query
        description: Used in pagination when number of courses exceed the maximum amount of results per page.
        schema:
          type: integer
          format: int32
      - name: per
        in: query
        description: Used in pagination to define amount of courses per page, when not defined the maximum is 20.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoursesListResponse'
        '401':
          description: Unauthorized - invalid or expired access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
        '403':
          description: Forbidden - not authorized to access this endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
  /current_user/courses/{course_id}:
    get:
      operationId: getCurrentUserCourse
      summary: Get a course for current user
      description: Return a course by its unique ID for the current authenticated user.
      tags:
      - Courses
      security:
      - OAuth2:
        - courses:read
      - AccessToken: []
      parameters:
      - name: course_id
        in: path
        required: true
        description: Return a course by its unique ID number.
        schema:
          type: integer
          format: int32
          minimum: 1
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CourseDetailResponse'
        '401':
          description: Unauthorized - invalid or expired access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
        '403':
          description: Forbidden - not authorized to access this endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
        '404':
          description: Course not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
  /current_user/courses/{course_id}/progress:
    get:
      operationId: getCurrentUserCourseProgress
      summary: Get course progress for current user
      description: Return the current authenticated user's progress in a specific course.
      tags:
      - Courses
      security:
      - OAuth2:
        - courses:read
      - AccessToken: []
      parameters:
      - name: course_id
        in: path
        required: true
        description: Return a course progress by its unique ID number.
        schema:
          type: integer
          format: int32
          minimum: 1
      - name: page
        in: query
        description: Used in pagination when number of lecture progresses exceed the maximum amount.
        schema:
          type: integer
          format: int32
      - name: per
        in: query
        description: Used in pagination to define amount of lecture progresses per page, when not defined the maximum is 20.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CourseProgressResponse'
        '401':
          description: Unauthorized - invalid or expired access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
        '403':
          description: Forbidden - not authorized to access this endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
        '404':
          description: Course not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
components:
  schemas:
    CourseSummary:
      type: object
      properties:
        id:
          type: integer
          description: Unique course identifier.
        name:
          type: string
          description: Course title.
        heading:
          type: string
          nullable: true
          description: The course subtitle, as set in the Information tab.
        description:
          type: string
          nullable: true
          description: Course description.
        is_published:
          type: boolean
          description: Publication status of the course.
        image_url:
          type: string
          nullable: true
          description: URL of the course image.
    ErrorResponse:
      type: object
      properties:
        message:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
          description: Error message or array of error messages.
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
          description: Total number of items.
        page:
          type: integer
          description: Current page number.
        from:
          type: integer
          description: First item position on current page.
        to:
          type: integer
          description: Last item position on current page.
        per_page:
          type: integer
          description: Number of items per page.
        number_of_pages:
          type: integer
          description: Total number of pages.
    OAuthErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error code (e.g., invalid_token, access_forbidden, resource_not_found, unmet_requirements).
        error_description:
          type: string
          description: Human-readable error description.
    LectureSectionProgress:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        lectures:
          type: array
          items:
            type: object
    CourseProgressDetail:
      type: object
      properties:
        id:
          type: integer
        certificate:
          type: object
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        enrolled_at:
          type: string
          format: date-time
        lecture_sections:
          type: array
          items:
            $ref: '#/components/schemas/LectureSectionProgress'
        percent_complete:
          type: number
    CoursesListResponse:
      type: object
      properties:
        courses:
          type: array
          items:
            $ref: '#/components/schemas/CourseSummary'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    CourseDetail:
      allOf:
      - $ref: '#/components/schemas/CourseSummary'
      - type: object
        properties:
          lecture_sections:
            type: array
            items:
              $ref: '#/components/schemas/LectureSection'
          author_bio:
            $ref: '#/components/schemas/AuthorBio'
    CourseProgressResponse:
      type: object
      properties:
        course_progress:
          $ref: '#/components/schemas/CourseProgressDetail'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    AuthorBio:
      type: object
      properties:
        name:
          type: string
          description: Author name.
        bio:
          type: string
          nullable: true
          description: Author biography.
        profile_image_url:
          type: string
          nullable: true
          description: Author profile image URL.
        user_id:
          type: integer
          nullable: true
          description: Associated user ID.
    CourseDetailResponse:
      type: object
      properties:
        course:
          $ref: '#/components/schemas/CourseDetail'
    LectureSection:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        is_published:
          type: boolean
        position:
          type: integer
        lectures:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              position:
                type: integer
              is_published:
                type: boolean
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: apiKey
      description: API key for Admin API authentication. Available on Growth plan and above.