Create chatbot

Create a new course chatbot by providing a name and a list of YouTube lecture video URLs.

POST /chatbot/create

Create chatbot

cURL

curl --request POST \
  --url https://api.example.com/chatbot/create \
  --header 'Content-Type: application/json' \
  --header 'x-access'\''courser-auth-token: <x-access'\''courser-auth-token>' \
  --data '
{
  "name": "<string>",
  "youtubeUrls": [
    "<string>"
  ]
}
'

200

{
  "course": {
    "_id": "<string>",
    "name": "<string>",
    "instructions": "<string>",
    "color": "<string>",
    "placeholder": "<string>",
    "backgroundImg": "<string>",
    "openAIAssistantID": "<string>",
    "openAIFiles": [
      "<string>"
    ],
    "transcriptions": [
      "<string>"
    ],
    "sourceFiles": [
      "<string>"
    ],
    "openAIKey": "<string>"
  }
}

Creates a new course, processes the provided YouTube lecture videos to extract transcriptions, and sets up an OpenAI assistant for the course. Authentication is required.

This endpoint performs heavy background work: downloading YouTube captions and building an OpenAI assistant configuration. Expect 30–90 seconds of processing time per video. The request will not return until processing is complete.

Request headers

x-access'courser-auth-token · string · required

Your JWT authentication token.

Request body

name · string · required

The display name for the chatbot and course.

youtubeUrls · string[] · required

An array of YouTube video URLs to use as the chatbot’s knowledge base. Each URL must be a standard watch URL.

URLs must use the format https://www.youtube.com/watch?v=VIDEO_ID. Shortened URLs (youtu.be), playlist URLs, and embed URLs are not supported.

Response

200 — Success

course · object · required

The newly created course object.

Show Course properties

_id · string

Unique identifier for the course.

name · string

The course display name.

instructions · string

The AI system prompt. Defaults to "You are a helpful AI assistant for a University classroom that answers questions for students about this course".

color · string

The chatbot accent color as a hex string. Defaults to "#fecc4e".

placeholder · string

The input field hint text. Defaults to "What is significant about horseshoe crabs".

backgroundImg · string

URL of the chatbot background image. Defaults to a Cloudinary-hosted image.

openAIAssistantID · string

The OpenAI assistant ID created for this course.

openAIFiles · string[]

IDs of files uploaded to OpenAI for retrieval.

transcriptions · string[]

Array of Transcription document IDs referencing the processed YouTube videos.

sourceFiles · string[]

Array of Source document IDs (MongoDB ObjectIds) for the processed YouTube videos. Each entry references a Source document containing the transcript chunks and embeddings.

openAIKey · string

Custom OpenAI API key for this course, if set. Empty string if using the platform default.

Example

cURL

curl --request POST \
  --url http://localhost:8000/chatbot/create \
  --header "x-access'courser-auth-token: <your_jwt_token>" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Introduction to Marine Biology",
    "youtubeUrls": [
      "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "https://www.youtube.com/watch?v=xvFZjo5PgG0"
    ]
  }'

200

{
  "course": {
    "_id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "name": "Introduction to Marine Biology",
    "instructions": "You are a helpful AI assistant for a University classroom that answers questions for students about this course",
    "color": "#fecc4e",
    "placeholder": "What is significant about horseshoe crabs",
    "backgroundImg": "https://res.cloudinary.com/dlk3ezbal/image/upload/v1699589098/jqmlca7vhr0cnzgdbaah.png",
    "openAIAssistantID": "asst_abc123xyz",
    "openAIFiles": ["file-abc123", "file-def456"],
    "transcriptions": ["64f1a2b3c4d5e6f7a8b9c0d2", "64f1a2b3c4d5e6f7a8b9c0d3"],
    "sourceFiles": [],
    "openAIKey": ""
  }
}