Build on Classcastle

Our developer API lets you integrate Classcastle into your own tools. Create custom dashboards, automate room management, and extend classroom management however you need.

Get started Contact us

What you can build

The API gives you programmatic access to rooms, students, and navigation commands.

Custom dashboards

Build your own teacher interface with exactly the features you need. Track student engagement, create custom views, and integrate with your existing tools.

Automated workflows

Schedule navigation changes, auto-create rooms for each class period, or integrate with your LMS to pull in student rosters automatically.

Analytics & reporting

Export room data, track usage patterns, and generate custom reports. Understand how your classrooms use Classcastle over time.

Getting started

Generate your API key, then make your first request.

1. Generate your API key

Go to api.classcastle.org/generateapikey to generate your API key. This creates an API-only account that can only be accessed via the API, keeping your main teacher account secure.

2. Authenticate your requests

Include your API key in the Authorization header as a Bearer token.

Authorization: Bearer your_api_key_here

3. Use the sleep helper

The classcastle.sleep() helper lets you add delays between API calls. Pass the number of seconds to wait.

classcastle.sleep = (seconds) => new Promise(resolve => setTimeout(resolve, seconds * 1000));

// Wait 2 seconds before the next action
await classcastle.sleep(2);

4. Make your first request

Create a room to verify everything is working.

curl https://api.classcastle.org/createroom \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Room"}'

Core endpoints

The most commonly used API endpoints for building integrations.

POST

/createroom

Create a new room. Optional trycode parameter to request a specific room code.

GET

/rooms

List all rooms for your account

GET

/rooms/{id}

Get details for a specific room

POST

/rooms/{id}/navigate

Send all students in a room to a URL

GET

/rooms/{id}/students

List all students in a room

GET

/rooms/{id}/activity

Get activity log for a room

POST

/rooms/deleteroom/{id}

Delete a room permanently

Example: Create, navigate, and delete

A complete example showing how to create a room, send students to a page, and delete the room when done.

// Helper function to sleep/delay
classcastle.sleep = (seconds) => new Promise(resolve => setTimeout(resolve, seconds * 1000));

// Create a new room
const response = await fetch('https://api.classcastle.org/createroom', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Period 3 - Science',
    trycode: 'SCI3'
  })
});

const room = await response.json();

// Wait 2 seconds before navigating
await classcastle.sleep(2);

// Navigate all students to a URL
await fetch(`https://api.classcastle.org/rooms/${room.id}/navigate`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://microbit.org'
  })
});

// Delete the room when done
await fetch(`https://api.classcastle.org/rooms/deleteroom/${room.id}`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key_here',
    'Content-Type': 'application/json'
  }
});

Troubleshooting

Common error codes and how to resolve them.

4001

The requested room code is already taken

When using the trycode parameter, this error means the code is already in use by another room. Try a different code or omit the parameter to let the system generate one.

4002

Invalid or missing API key

Check that your Authorization header includes a valid Bearer token. Generate a new key at devlabs.classcastle.org/generateapikey if needed.

4003

Room does not exist

The room ID you're trying to access doesn't exist or you don't have permission to view it.

4004

Invalid URL provided

The URL you're trying to navigate to is malformed or not allowed. Ensure it starts with http:// or https://.

429

Too many requests

You've exceeded the rate limit for API calls. Wait a moment before retrying, or contact us about increasing your limit.

Ready to build?

Generate your API key and start integrating Classcastle into your workflow today.

Generate API key

Questions? Email us