Skip to content
Optio Docs

Quick Start

This guide walks you through setting up a TypeScript project from scratch and making your first API call with the Optio Teachable SDK.

Prerequisites

Section titled “Prerequisites”
  • Node.js v18 or higher
  • A Teachable account with an API key (find yours from your dashboard Settings -> API keys)

Installation

Section titled “Installation”

1. Create a new project

Section titled “1. Create a new project”
Terminal window
mkdir my-teachable-app
cd my-teachable-app
npm init -y

2. Install TypeScript and ts-node

Section titled “2. Install TypeScript and ts-node”

ts-node lets you run TypeScript files directly without a separate compile step — ideal for scripts and quick integrations.

Terminal window
npm install --save-dev typescript ts-node @types/node

3. Create a tsconfig.json

Section titled “3. Create a tsconfig.json”
Terminal window
npx tsc --init

Then replace the contents of tsconfig.json with this recommended configuration:

{
  "compilerOptions": {
    "target": "es2022",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

4. Install the SDK and dotenv

Section titled “4. Install the SDK and dotenv”
Terminal window
npm install optio-teachable dotenv

dotenv loads environment variables from a .env file so your API key never appears in your source code.

Configuration

Section titled “Configuration”

1. Create a .env file

Section titled “1. Create a .env file”

In the root of your project, create a .env file:

Terminal window
TEACHABLE_API_KEY=your-api-key-here

2. Add .env to .gitignore

Section titled “2. Add .env to .gitignore”

If you’re using Git, make sure your API key is never committed:

Terminal window
echo ".env" >> .gitignore

Your First Script

Section titled “Your First Script”

Create a file called index.ts in your project root:

import { config } from 'dotenv';
import { TeachableClient } from 'optio-teachable';


// Load environment variables from .env
config();


async function main() {
    const teachable = new TeachableClient(process.env.TEACHABLE_API_KEY!);


    try {
        const { courses } = await teachable.v1.courses.getList();
        console.log(`Found ${courses.length} courses:`);
        courses.forEach(course => {
            console.log(` - ${course.name} (published: ${course.is_published})`);
        });
    } catch (error) {
        console.error('API call failed:', error);
    }
}


main();

Run it

Section titled “Run it”
Terminal window
npx ts-node index.ts

You should see your Teachable courses listed in the terminal.

Exploring Further

Section titled “Exploring Further”

Here are a few more examples to get you started:

Fetch a paginated user list:

const { users, meta } = await teachable.v1.users.getList(1, 20);
console.log(`Page 1 of ${meta?.number_of_pages} — ${meta?.total} users total`);

Look up a user by email:

const { users } = await teachable.v1.users.getByEmail('student@example.com');
const user = users[0];
console.log(`Found user: ${user?.name} (ID: ${user?.id})`);

Filter transactions by date range:

const { transactions } = await teachable.v1.transactions.getList(1, 50, {
    startDate: '2026-01-01',
    endDate: '2026-03-31',
});
console.log(`Found ${transactions.length} transactions in Q1 2026`);

Get a course with full lecture structure:

const { course } = await teachable.v1.courses.getById(123);
console.log(`${course.name} has ${course.lecture_sections?.length} sections`);

Debug Mode

Section titled “Debug Mode”

Pass true as the second argument to TeachableClient to enable request and response logging — useful when exploring the API or troubleshooting unexpected responses:

const teachable = new TeachableClient(process.env.TEACHABLE_API_KEY!, true);

This will log all outgoing requests and full response bodies to the console, prefixed with [Teachable Debug].

Using TypeScript Types

Section titled “Using TypeScript Types”

All response types are exported from the SDK and can be used to type your own functions:

import type { Course, UserDetail, Transaction } from 'optio-teachable';


function formatCourse(course: Course): string {
    return `${course.name} — ${course.is_published ? 'Live' : 'Draft'}`;
}

Next Steps

Section titled “Next Steps”