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.