Teachworks Lessons API

openapi: 3.2.0
info:
  title: Teachworks Availabilities Lessons API
  description: 'The Teachworks API is a REST API that lets Teachworks users build custom integrations against the data in their Teachworks account - customers (families and independent students), students, employees (teachers and staff), lessons and events, services, invoices, payments, and teacher wages. Teachworks is business management software for tutoring companies, music schools, and test-prep centers. The API is available on the Growth and Premium plans. All requests are made over HTTPS to https://api.teachworks.com/v1 and authenticated with an account API token passed in the Authorization header using the scheme "Authorization: Token token=API_TOKEN". Responses are JSON. List endpoints are paginated (20 records per page by default, up to 80 via per_page) and support field-based search and id range filters. The API is rate limited to 4 requests per second per token. There is no native webhook or WebSocket surface; event-driven integrations are handled through Zapier, Make, and Integrately polling. All paths in this document are confirmed against the official Teachworks Postman API reference.'
  version: '1.0'
  contact:
    name: Teachworks Support
    url: https://teachworks.com/addons/api
    email: support@teachworks.com
servers:
- url: https://api.teachworks.com/v1
  description: Teachworks API
security:
- tokenAuth: []
tags:
- name: Lessons
  description: Scheduled lessons, participants, and completion.
paths:
  /lessons:
    get:
      operationId: listLessons
      tags:
      - Lessons
      summary: List all Lessons
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          $ref: '#/components/responses/CollectionOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createLesson
      tags:
      - Lessons
      summary: Create a Lesson
      requestBody:
        $ref: '#/components/requestBodies/GenericJson'
      responses:
        '200':
          $ref: '#/components/responses/ResourceOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /lessons/{id}:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      operationId: getLesson
      tags:
      - Lessons
      summary: Retrieve a Lesson
      responses:
        '200':
          $ref: '#/components/responses/ResourceOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /lessons/{id}/add_student:
    parameters:
    - $ref: '#/components/parameters/Id'
    put:
      operationId: addStudentToLesson
      tags:
      - Lessons
      summary: Add Student to Lesson
      requestBody:
        $ref: '#/components/requestBodies/GenericJson'
      responses:
        '200':
          $ref: '#/components/responses/ResourceOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /lessons/{id}/complete:
    parameters:
    - $ref: '#/components/parameters/Id'
    put:
      operationId: completeLesson
      tags:
      - Lessons
      summary: Complete a Lesson
      requestBody:
        $ref: '#/components/requestBodies/GenericJson'
      responses:
        '200':
          $ref: '#/components/responses/ResourceOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  parameters:
    PerPage:
      name: per_page
      in: query
      required: false
      description: Number of records per page. Defaults to 20, maximum 80.
      schema:
        type: integer
        default: 20
        maximum: 80
    Id:
      name: id
      in: path
      required: true
      description: The ID of the resource.
      schema:
        type: integer
    Page:
      name: page
      in: query
      required: false
      description: 1-based page number for pagination. Defaults to 1.
      schema:
        type: integer
        default: 1
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    CollectionOk:
      description: A paginated list of resources.
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
              additionalProperties: true
    ResourceOk:
      description: A single resource.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
    UnprocessableEntity:
      description: Validation failed for the submitted attributes.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        errors:
          type: array
          items:
            type: string
  requestBodies:
    GenericJson:
      required: true
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Account API token passed in the Authorization header using the scheme "Authorization: Token token=API_TOKEN". Generate a token on the Integrations and Add-ons page in Teachworks. All requests must be over HTTPS.'