Documentation

API Guide

Version 1.2.0 • Last Updated: April 2026

Welcome to the Ilmfun API Documentation. This guide explains how to integrate with the Ilmfun platform, specifically for Godot game frontends and custom client implementations.

1. Base URL

All API endpoints are served over HTTPS and use a standard RESTful interface.

BASE_URL: https://ilmfun.com/api
PROTOCOL: HTTPS/1.1

2. Authentication

The API uses JWT-based authentication. Most endpoints require an Authorization: Bearer <token> header.

2.1 Google Login

Exchange a Google ID Token for an Ilmfun Access Token and Refresh Token.

POST /api/auth/google
{
  "id_token": "YOUR_GOOGLE_ID_TOKEN"
}

2.2 Refresh Token

Get a new access token using your refresh token to maintain your session.

POST /api/token
{
  "grant_type": "refresh_token",
  "refresh_token": "YOUR_REFRESH_TOKEN"
}

3. Models (VRM)

Models in Ilmfun are standard VRM files. The game frontend is responsible for loading these assets at runtime.

3.1 List Models

Retrieve a list of available 3D models or filter by a specific user ID.

GET /api/models
GET /api/models?user_id={id}

3.2 Model Response

The API returns model metadata along with direct URLs to the stored assets:

{
  "id": 16,
  "name": "Battle Mage",
  "file_url": "https://storage.ilmfun.com/models/1_16.vrm",
  "file_size": 2450123
}

4. Rooms

Rooms enable real-time interaction between users via LiveKit.

4.1 Join a Room

Request a connection token to join a specific room.

POST /api/schools/{id}/rooms/{identifier}/join

4.2 Connection Details

The response includes the credentials needed for the LiveKit SDK:

{
  "token": "LIVEKIT_CONNECTION_TOKEN",
  "url": "wss://livekit.ilmfun.com",
  "room": "primary-classroom"
}

5. Godot Integration

To use these services in a Godot project:

Asset Loading: Use a VRM loader plugin to download and display file_url assets.
Networking: Use the LiveKit Godot SDK for voice and data synchronization.
Security: Store your JWT tokens securely in the local application state.

For technical support or further inquiries, please contact us at hello@ilmfun.com.