Skip to content

HTTP API

Jump to bottom
Mr. Smith edited this page Oct 23, 2025 · 21 revisions

Usage in Python

Install requests module

pip install requests

Set up constants

FBJS_URL = 'http://172.16.3.100:420/api'
API_KEY = 'get your own api key and put it here'

You can get your API key by logging into the instance of FormbarJS you wish to interact with and going to /profile.

Prepare header for API calls

headers = {
    'API': API_KEY,
    'Content-Type': 'application/json'
}

Make the GET request

import requests

try:
    response = requests.get(f'{FBJS_URL}/me', headers=headers)
    response.raise_for_status()
    data = response.json()
    print(data)
except requests.exceptions.RequestException as err:
    print('Connection closed due to errors:', err)

Usage in NodeJS

Set up constants

Set the address for the FormbarJS instance you wish to connect to, and your API Key...

const FBJS_URL = 'http://172.16.3.100:420/api';
const API_KEY = 'get ur own api key and put it here';

You can get your API key by logging into the instance of FormbarJS you wish to interact with and going to /profile.

Prepare header for API calls

let reqOptions =
{
   method: 'GET',
   headers: {
      'API': API_KEY,
      'Content-Type': 'application/json'
   }
};

Make the GET request

fetch(`${FBJS_URL}/me`, reqOptions)
   .then((response) => {
      // Convert received data to JSON
      return response.json();
   })
   .then((data) => {
      // Log the data if the request is successful
      console.log(data);
   })
   .catch((err) => {
      // If there's a problem, handle it...
      if (err) console.log('connection closed due to errors', err);
   });

Overview

Authentication

Formbar.js supports two authentication methods:

1. API Key Authentication

Include an API header with a valid API key in your requests.

// JavaScript example
const headers = {
    'API': 'your-api-key-here',
    'Content-Type': 'application/json'
};

fetch('https://formbar.example.com/api/me', { headers });
# Python example
import requests

headers = {
    'API': 'your-api-key-here',
    'Content-Type': 'application/json'
}

response = requests.get('https://formbar.example.com/api/me', headers=headers)

2. Session Authentication

For web-based applications, users can authenticate through the web interface and use session-based authentication.

Getting Your API Key

  1. Log into your Formbar.js instance
  2. Navigate to /profile
  3. Copy your API key from the profile page
  4. Include it in the API header of all requests

Authentication Errors

// 401 - Invalid or missing API key
{
    "error": "Invalid API key"
}

// 401 - User not found
{
    "error": "user does not exist in this class"
}

// 403 - Insufficient permissions
{
    "error": "You do not have permission to access this page."
}

Permissions

Permissions are hierarchical (higher number includes all capabilities of lower numbers):

Role Level
Manager 5
Teacher 4
Mod 3
Student 2
Guest 1
Banned 0

Error Handling

Formbar.js uses standard HTTP status codes and returns JSON error responses.

Common HTTP Status Codes

Status Description Common Causes
200 Success Request completed successfully
400 Bad Request Invalid parameters, missing required fields
401 Unauthorized Invalid API key, user not found
403 Forbidden Insufficient permissions, not in class
404 Not Found Class not started, user not found
500 Server Error Internal server error, database issues

Error Response Format

All error responses follow this format:

{
    "error": "Error message describing what went wrong"
}

Common Error Scenarios

Authentication Errors

// Invalid API key
{
    "error": "Invalid API key"
}

// User not found
{
    "error": "user does not exist in this class"
}

Permission Errors

// Insufficient permissions
{
    "error": "You do not have permission to access this page."
}

// Not in class
{
    "error": "User is not logged into the selected class"
}

Validation Errors

// Missing required field
{
    "error": "No API provided."
}

// Invalid parameter
{
    "error": "Invalid type"
}

// Invalid PIN
{
    "success": false,
    "message": "Invalid PIN"
}

Resource Errors

// Class not started
{
    "error": "Class not started"
}

// User not found
{
    "error": "User not found."
}

Error Handling Best Practices

// JavaScript error handling example
async function makeApiRequest(url, options) {
    try {
        const response = await fetch(url, options);
        
        if (!response.ok) {
            const errorData = await response.json();
            throw new Error(`API Error ${response.status}: ${errorData.error || errorData.message}`);
        }
        
        return await response.json();
    } catch (error) {
        console.error('API Request failed:', error.message);
        throw error;
    }
}

// Usage
try {
    const userData = await makeApiRequest('https://formbar.example.com/api/me', {
        headers: { 'API': 'your-api-key-here' }
    });
    console.log('User data:', userData);
} catch (error) {
    console.error('Failed to fetch user data:', error.message);
}
# Python error handling example
import requests
from requests.exceptions import RequestException

def make_api_request(url, headers=None, json=None):
    try:
        response = requests.get(url, headers=headers, json=json)
        response.raise_for_status()  # Raises exception for 4xx/5xx status codes
        return response.json()
    except requests.exceptions.HTTPError as e:
        error_data = response.json() if response.content else {}
        raise Exception(f"API Error {response.status_code}: {error_data.get('error', 'Unknown error')}")
    except RequestException as e:
        raise Exception(f"Request failed: {str(e)}")

# Usage
try:
    headers = {'API': 'your-api-key-here'}
    user_data = make_api_request('https://formbar.example.com/api/me', headers=headers)
    print('User data:', user_data)
except Exception as e:
    print(f'Failed to fetch user data: {e}')

Returnable Objects

Student

Represents a user's data within a class context. Contains both global and class-specific information.

// Example Student Object
{
   "loggedIn": true,
   "username": "john.doe@example.com",
   "id": 123,
   "permissions": 4,  // Teacher level
   "classPermissions": 5,  // Manager level in this class
   "help": null,  // No active help request
   "break": false,  // Not on break
   "pogMeter": 250,  // Current pog meter progress
   "displayName": "John Doe",
   "digipogs": 1500,  // Total digipogs owned
   "verified": true
}

Field Descriptions:

  • loggedIn: Whether the user is currently active in the class
  • username: User's email address (used as identifier)
  • id: Unique user identifier
  • permissions: Global permission level (0-5)
  • classPermissions: Permission level within the current class
  • help: Help request status (null, false, or help object)
  • break: Break status (null, false, true, or break request string)
  • pogMeter: Current progress toward next digipog reward (0-500)
  • displayName: User's chosen display name
  • digipogs: Total digipogs owned by the user
  • verified: Whether the user's account is verified

Poll

Represents the current poll state in a class, including responses and configuration.

// Example Poll Object
{
   "status": true,  // Poll is active
   "totalStudents": 25,  // Number of students in class
   "responses": {
      "Option A": {
         "answer": "Option A",
         "weight": 1.0,
         "color": "#FF5733",
         "responses": 8
      },
      "Option B": {
         "answer": "Option B", 
         "weight": 1.0,
         "color": "#33FF57",
         "responses": 12
      },
      "Option C": {
         "answer": "Option C",
         "weight": 1.0,
         "color": "#3357FF",
         "responses": 5
      }
   },
   "textRes": "What is your favorite programming language?",
   "prompt": "Choose your preferred language:",
   "weight": 1,  // Poll weight for scoring
   "blind": false,  // Students can see others' responses
   "allowTextResponses": false,
   "allowMultipleResponses": false
}

Field Descriptions:

  • status: Whether a poll is currently active
  • totalStudents: Total number of students in the class
  • responses: Object containing poll response data by option
  • textRes: The poll question or prompt text
  • prompt: Display text for the poll
  • weight: Contribution weight to quiz or pog meter
  • blind: Whether responses are hidden from other students
  • allowTextResponses: Whether free-text responses are enabled
  • allowMultipleResponses: Whether multiple selections are allowed

Poll Response

Individual response option within a poll, containing answer details and statistics.

// Example Poll Response Object
{
   "answer": "JavaScript",
   "weight": 1.0,  // Response weight
   "color": "#F7DF1E",  // Hex color for display
   "responses": 15  // Number of students who selected this option
}

Field Descriptions:

  • answer: The response option text
  • weight: Weight multiplier for scoring (typically 1.0)
  • color: Hex color code for visual representation
  • responses: Count of students who selected this option

Help

Represents a student's help request with timing information.

// Example Help Object
{
   "reason": "Need help with the assignment",
   "time": {
      "hours": 2,
      "minutes": 15,
      "seconds": 30
   }
}

Field Descriptions:

  • reason: Description of why help is needed
  • time: Object containing the duration since help was requested
    • hours: Hours since request
    • minutes: Minutes since request
    • seconds: Seconds since request

Class

Represents a classroom session with students, polls, and configuration.

// Example Class Object
{
   "id": 456,
   "className": "Advanced Programming",
   "students": {
      "john.doe@example.com": { /* Student object */ },
      "jane.smith@example.com": { /* Student object */ }
   },
   "poll": { /* Poll object */ },
   "key": "ABC123",  // Class access key
   "lesson": {
      "title": "Introduction to APIs",
      "steps": ["Overview", "Examples", "Practice"]
   },
   "activeLesson": true,
   "currentStep": 1,
   "quiz": false,
   "mode": "poll"  // Current class mode
}

User

Public user information returned by user endpoints.

// Example User Object
{
   "id": 123,
   "email": "john.doe@example.com",  // Only visible to self/manager
   "permissions": 4,  // Teacher level
   "digipogs": 1500,
   "displayName": "John Doe",
   "verified": true
}

Endpoints

Method Path Permission Level Description
GET /api/me Any (API or session) Provides user's data based on API key/session.
GET /api/manager Manager Retrieves manager data (users and classrooms).
GET /api/ip/:type Manager Lists IP whitelist/blacklist entries.
POST /api/ip/:type Manager Adds IP to whitelist/blacklist.
PUT /api/ip/:type/:id Manager Updates IP whitelist/blacklist entry.
DELETE /api/ip/:type/:id Manager Removes IP from whitelist/blacklist.
POST /api/ip/:type/toggle Manager Toggles IP whitelist/blacklist status.
GET /api/class/{classId} Student in class Class snapshot (students, poll, settings).
GET /api/class/{classId}/students Manage class Students of class (includes guests if present).
GET /api/class/{classId}/polls Student in class Current poll status and aggregated responses.
GET /api/class/{classId}/permissions Student in class Class permission thresholds.
GET /api/class/{classId}/active Manage class Whether the class is currently active.
GET /api/class/{classId}/banned Teacher/Mod List of banned users in the class.
GET /api/class/{classId}/help/request Student in class Create a help ticket for the requester.
GET /api/class/{classId}/students/{userId}/help/delete Control polls Delete a student's help ticket.
GET /api/class/{classId}/students/{userId}/break/approve Break & Help Approve a student's break request.
POST /api/class/{classId}/students/{userId}/break/deny Break & Help Deny a student's break request.
POST /api/class/{classId}/break/request Student in class Request a break in the current class.
POST /api/class/{classId}/break/end Student in class End the current user's break.
POST /api/class/{classId}/start Manage class Start the class session.
POST /api/class/{classId}/end Manage class End the class session.
POST /api/class/{classId}/join Guest Join the current class session.
POST /api/class/{classId}/leave Guest Leave the current class session (remain in classroom).
POST /api/room/{code}/join Guest Join a classroom by invite/code.
POST /api/class/{classId}/leave Guest Leave the classroom entirely (room leave).
GET /api/room/{id}/links Member of class Get class links.
POST /api/room/{id}/links/add Teacher Add a class link.
POST /api/room/{id}/links/change Teacher Update a class link.
POST /api/room/{id}/links/remove Teacher Remove a class link.
GET /api/room/tags Member of class Get class tags.
POST /api/room/tags Teacher Set class tags.
GET /api/class/{id}/banned Teacher/Mod List of banned users in the class.
POST /api/class/{classId}/polls/create Control polls Create/start a poll (legacy or object body supported).
POST /api/class/{classId}/polls/end Control polls End the current poll.
POST /api/class/{classId}/polls/clear Control polls Clear the current poll (no save).
POST /api/class/{classId}/polls/response Student in class Submit a poll response.
POST /api/digipogs/award Manage class Award digipogs to a user.
POST /api/digipogs/transfer Student Transfer digipogs between users (PIN required).
GET /api/user/{id} Any Public user info; includes email for self/manager.
GET /api/user/{id}/ownedClasses Teacher/self/manager List classes owned by the user.
GET /api/user/{id}/class Self/manager The user's active class (id, name) if any.
POST /api/user/{id}/verify Manager Verify a user's account.
POST /api/user/{email}/perm Manager Update user permissions.
GET /api/user/{id}/delete Manager Delete a user account.
GET /api/user/{id}/ban Manager Ban a user account.
GET /api/user/{id}/unban Manager Unban a user account.
GET /api/apiPermissionCheck Logged-in in class Check if API key user has a specific class capability.

Endpoint Information

This includes information regarding both endpoint responses and parameters.

GET /me

Retrieves the current user's information based on their API key or session.

Authentication

  • API Key: Include API header with valid key
  • Session: User must be logged in via web interface

Response

Parameter Type Permissions Description
loggedIn Boolean Any Whether the user is currently logged in.
id Integer Any The user's unique identifier.
email String Any The user's email address.
permissions Integer Any The user's global permission level.
classPermissions Integer Any The user's permission level within a class.
help Object | False | Null Any null if no help ticket exists; otherwise an object representing the user's help ticket.
break String | Boolean | Null Any null if logged out, false if not on break, true if on break, or a string describing a pending break request.
pogMeter Integer Any User's current pog meter progress.
classId Integer | Null Any The user's current class ID, or null if not in a class.

Example Request

// Using fetch with API key
const response = await fetch('https://formbar.example.com/api/me', {
    method: 'GET',
    headers: {
        'API': 'your-api-key-here',
        'Content-Type': 'application/json'
    }
});

const userData = await response.json();
console.log('User data:', userData);
# Using requests with API key
import requests

headers = {
    'API': 'your-api-key-here',
    'Content-Type': 'application/json'
}

response = requests.get('https://formbar.example.com/api/me', headers=headers)
user_data = response.json()
print('User data:', user_data)

Example Response

{
    "loggedIn": true,
    "id": 123,
    "email": "john.doe@example.com",
    "permissions": 4,
    "classPermissions": 5,
    "help": null,
    "break": false,
    "pogMeter": 250,
    "classId": 456,
    "displayName": "John Doe",
    "digipogs": 1500,
    "verified": true
}

Error Responses

// 401 - Invalid API key
{
    "error": "Invalid API key"
}

// 500 - Server error
{
    "error": "There was a server error try again."
}

GET /manager

Response

Parameter Type Permissions Description
users Array Manager Array of all users in the system.
classrooms Array Manager Array of all classrooms in the system.

Errors

Status Description
403 Manager permissions required.
500 Server error.

GET /ip/:type

Path Parameters

Parameter Type Permissions Description
type String Manager Either "whitelist" or "blacklist".

Response

Parameter Type Permissions Description
active Boolean Manager Whether the IP list is currently active.
ips Array Manager Array of IP entries with id and ip fields.

Errors

Status Description
400 Invalid type (must be "whitelist" or "blacklist").
403 Manager permissions required.
500 Server error.

POST /ip/:type

Path Parameters

Parameter Type Permissions Description
type String Manager Either "whitelist" or "blacklist".

Body

Parameter Type Required Description
ip String Yes IP address to add.

Response

Parameter Type Permissions Description
message String Manager Success message.

Errors

Status Description
400 Invalid IP address or missing IP.
403 Manager permissions required.
500 Server error.

PUT /ip/:type/:id

Path Parameters

Parameter Type Permissions Description
type String Manager Either "whitelist" or "blacklist".
id Number Manager ID of the IP entry to update.

Body

Parameter Type Required Description
ip String Yes New IP address.

Response

Parameter Type Permissions Description
message String Manager Success message.

Errors

Status Description
400 Invalid IP address or missing IP.
403 Manager permissions required.
404 IP entry not found.
500 Server error.

DELETE /ip/:type/:id

Path Parameters

Parameter Type Permissions Description
type String Manager Either "whitelist" or "blacklist".
id Number Manager ID of the IP entry to delete.

Response

Parameter Type Permissions Description
message String Manager Success message.

Errors

Status Description
403 Manager permissions required.
404 IP entry not found.
500 Server error.

POST /ip/:type/toggle

Path Parameters

Parameter Type Permissions Description
type String Manager Either "whitelist" or "blacklist".

Response

Parameter Type Permissions Description
message String Manager Success message.

Errors

Status Description
403 Manager permissions required.
500 Server error.

GET /class/{classId}

Retrieves a complete snapshot of a class including students, current poll, and class settings.

Authentication

  • API Key: Include API header with valid key
  • Session: User must be logged in and member of the class

Path Parameters

Parameter Type Required Description
classId String Yes The unique identifier of the class

Response

Parameter Type Permissions Description
id Integer Student The class's unique identifier.
className String Student The name of the class.
students Object Mixed Object containing all students in the class. Each key is a username; each value is a student object.

Permission details:
  • loggedIn, id, username: Student
  • permissions, classPermissions, help, break, pogMeter: Mod or Teacher (teachers see full details)
poll Object Student The current poll object.
key String Student Class access key.
lesson Object Student The current lesson object.
activeLesson Boolean Student Whether there's an active lesson.
currentStep Integer Student The current lesson step.
quiz Boolean Student Whether there's an active quiz.
mode String Student The current mode (e.g., poll, quiz, lesson, game).

Example Request

// Get class information
const response = await fetch('https://formbar.example.com/api/class/456', {
    method: 'GET',
    headers: {
        'API': 'your-api-key-here',
        'Content-Type': 'application/json'
    }
});

const classData = await response.json();
console.log('Class data:', classData);
# Get class information
import requests

headers = {
    'API': 'your-api-key-here',
    'Content-Type': 'application/json'
}

response = requests.get('https://formbar.example.com/api/class/456', headers=headers)
class_data = response.json()
print('Class data:', class_data)

Example Response

{
    "id": 456,
    "className": "Advanced Programming",
    "students": {
        "john.doe@example.com": {
            "loggedIn": true,
            "id": 123,
            "username": "john.doe@example.com",
            "permissions": 4,
            "classPermissions": 5,
            "help": null,
            "break": false,
            "pogMeter": 250,
            "displayName": "John Doe",
            "digipogs": 1500,
            "verified": true
        },
        "jane.smith@example.com": {
            "loggedIn": true,
            "id": 124,
            "username": "jane.smith@example.com",
            "permissions": 2,
            "classPermissions": 2,
            "help": {
                "reason": "Need help with the assignment",
                "time": {
                    "hours": 0,
                    "minutes": 5,
                    "seconds": 30
                }
            },
            "break": false,
            "pogMeter": 100,
            "displayName": "Jane Smith",
            "digipogs": 750,
            "verified": true
        }
    },
    "poll": {
        "status": true,
        "totalStudents": 2,
        "responses": {
            "JavaScript": {
                "answer": "JavaScript",
                "weight": 1.0,
                "color": "#F7DF1E",
                "responses": 1
            },
            "Python": {
                "answer": "Python",
                "weight": 1.0,
                "color": "#3776AB",
                "responses": 1
            }
        },
        "textRes": "What is your favorite programming language?",
        "prompt": "Choose your preferred language:",
        "weight": 1,
        "blind": false,
        "allowTextResponses": false,
        "allowMultipleResponses": false
    },
    "key": "ABC123",
    "lesson": {
        "title": "Introduction to APIs",
        "steps": ["Overview", "Examples", "Practice"]
    },
    "activeLesson": true,
    "currentStep": 1,
    "quiz": false,
    "mode": "poll"
}

Error Responses

// 403 - User not in class
{
    "error": "User is not logged into the selected class"
}

// 404 - Class not started
{
    "error": "Class not started"
}

// 500 - Server error
{
    "error": "There was a server error try again."
}

GET /class/{classId}/students

Response

Parameter Type Permissions Description
students Object Mixed Object of all students in the class. See student object.

Permission details:
  • loggedIn, id, username: Student
  • permissions, classPermissions, help, break, quizScore, pogMeter: Mod or Teacher (teachers see full details)

GET /class/{classId}/polls

Response

Parameter Type Permissions Description
status Boolean Any Whether a poll is currently active.
totalStudents Integer Any Total number of students in the class.
responses Object Any Poll responses by option. See poll response object.
textRes String Any The current poll question.
prompt String Any The poll’s display text or question prompt.
weight Boolean Any Indicates the poll’s contribution weight to the quiz or pog meter.
blind Boolean Any Whether the poll is blind (students can’t see others’ responses).

API Reference

GET /apiPermissionCheck

Parameters

Parameter Type Permissions Description
api String Any The API route or endpoint being checked.
permissionType String Any The permission type to verify against the current user or class context.

Response

Parameter Type Permissions Description
allowed Object Any Returns { allowed: true } if permitted, otherwise { reason: "..." }.

Errors

Status Description
400 Invalid or missing parameters.
403 Permission denied.
500 Internal server error.

GET /api/class/{id}/permissions

Path Parameters

Parameter Type Permissions Description
id Number Logged In The unique class ID. Must be a member of the class.

Response

Parameter Type Permissions Description
thresholds Object Teacher / Mod Permission thresholds for the class.

Errors

Status Description
403 User is not in the class.
404 Class not active.

GET /api/class/{id}/active

Path Parameters

Parameter Type Permissions Description
id Number Logged In The class ID. Must be a member of the class.

Response

Parameter Type Permissions Description
isActive Boolean Any Whether the class is currently active.

Errors

Status Description
403 Not a member of the classroom.
500 Server error.

GET /api/class/{id}/banned

Path Parameters

Parameter Type Permissions Description
id Number Teacher / Mod The class ID.

Response

Parameter Type Permissions Description
id Number Teacher / Mod Banned user ID.
email String Teacher / Mod User email.
displayName String Teacher / Mod Display name of the user.

Errors

Status Description
404 Class not started.
500 Server error.

GET /api/class/{id}/help/request

Path Parameters

Parameter Type Permissions Description
id Number Logged In Class ID.

Response

Parameter Type Permissions Description
message String Any Returns a success message.

Errors

Status Description
403 Not in class.
500 { error: string }.

GET /api/class/{id}/students/{userId}/help/delete

Path Parameters

Parameter Type Permissions Description
id Number Teacher / Mod Class ID.
userId Number Teacher / Mod Student ID.

Authentication

Class permission: controlPolls

Response

Parameter Type Permissions Description
message String Any Success message.

Errors

Status Description
500 { error: string }.

GET /api/class/{id}/students/{userId}/break/approve

Path Parameters

Parameter Type Permissions Description
id Number Teacher / Mod Class ID.
userId Number Teacher / Mod Student ID.

Response

Parameter Type Permissions Description
message String Any Success message.

Errors

Status Description
403 Not permitted.
500 { error: string }.

POST /api/class/{id}/students/{userId}/break/deny

Path Parameters

Parameter Type Permissions Description
id Number Teacher / Mod Class ID.
userId Number Teacher / Mod Student ID.

Response

Parameter Type Permissions Description
message String Any Success message.

Errors

Status Description
403 Not permitted.
500 { error: string }.

POST /api/class/{id}/break/request

Path Parameters

Parameter Type Permissions Description
id Number Logged In Class ID.

Body

Parameter Type Required Description
reason String Yes Text reason for the break.

Response

Parameter Type Permissions Description
message String Any Success message.

Errors

Status Description
400 { error: 'A reason for the break must be provided.' }
403/500 Authorization or server error.

POST /api/class/{id}/break/end

Path Parameters

Parameter Type Permissions Description
id Number Logged In Class ID.

Response

Parameter Type Permissions Description
message String Any Success message.

Errors

Status Description
403 Authorization error.
500 Server error.

POST /api/class/{id}/start

Path Parameters

Parameter Type Permissions Description
id Number Teacher Class ID.

Authentication

Class permission: manageClass

Response

Parameter Type Permissions Description
message String Any Success message.

Errors

Status Description
500 Server error.

POST /api/class/{id}/end

Path Parameters

Parameter Type Permissions Description
id Number Teacher Class ID.

Authentication

Class permission: manageClass

Response

Parameter Type Permissions Description
message String Any Success message.

Errors

Status Description
500 Server error.

POST /api/class/{id}/join

Path Parameters

Parameter Type Permissions Description
id Number Logged In Class ID.

Response

Parameter Type Permissions Description
message String Any { message: 'Success' }

Errors

Status Description
500 { error: string }.

POST /api/class/{id}/leave (session)

Path Parameters

Parameter Type Permissions Description
id Number Logged In Class ID.

Response

Parameter Type Permissions Description
message String Any { message: 'Success' }

Errors

Status Description
403 Unauthorized.
500 { error: string }.

POST /api/room/{code}/join

Path Parameters

Parameter Type Permissions Description
code String Any Room code to join.

Response

Parameter Type Permissions Description
message String Any { message: 'Success' }

Errors

Status Description
500 { error: string }.

POST /api/class/{id}/leave (room)

Path Parameters

Parameter Type Permissions Description
id Number Logged In Class ID.

Response

Parameter Type Permissions Description
message String Any { message: 'Success' }

Errors

Status Description
500 { error: string }.

GET /api/room/{id}/links

Path Parameters

Parameter Type Permissions Description
id Number Member The class ID.

Response

Parameter Type Permissions Description
links Array Member Array of { name: string, url: string }.

Errors

Status Description
500 { error: string }.

POST /api/room/{id}/links/add

Path Parameters

Parameter Type Permissions Description
id Number Teacher The class ID.

Body

Parameter Type Required Description
name String Yes Link display name.
url String Yes URL to add.

Response

Parameter Type Permissions Description
message String Teacher 'Link added successfully.'

Errors

Status Description
400 { error: 'Name and URL are required.' }
500 Server error.

POST /api/room/{id}/links/change

Path Parameters

Parameter Type Permissions Description
id Number Teacher Class ID.

Body

Parameter Type Required Description
name String Yes New name for the link.
url String Yes Updated link URL.
oldName String Optional Previous link name to replace.

Response

Parameter Type Permissions Description
message String Teacher 'Link updated successfully.'

Errors

Status Description
400 { error: 'Name and URL are required.' }
500 Server error.

POST /api/room/{id}/links/remove

Path Parameters

Parameter Type Permissions Description
id Number Teacher Class ID.

Body

Parameter Type Required Description
name String Yes Link name to remove.

Response

Parameter Type Permissions Description
message String Teacher 'Link removed successfully.'

Errors

Status Description
400 { error: 'Name is required.' }
500 Server error.

GET /api/room/tags

Response

Parameter Type Permissions Description
tags String[] Any Array of class tags.

Errors

Status Description
404 { error: 'Class not found or not loaded.' }
500 Server error.

POST /api/room/tags

Body

Parameter Type Required Description
tags String[] Yes Array of tags to assign.

Response

Parameter Type Permissions Description
message String Any 'Success'.

Errors

Status Description
400 { error: 'tags must be an array of strings' }
404/500 Not found or server error.

POST /api/class/{id}/polls/create

Creates and starts a new poll in the specified class.

Authentication

  • API Key: Include API header with valid key
  • Session: User must be logged in and member of the class
  • Permission: Teacher/Mod level with poll control permissions

Path Parameters

Parameter Type Required Description
id Number Yes Class ID where poll will be created

Body

Parameter Type Required Description
prompt String Yes Poll question or prompt text
answers Array Yes Array of { answer, weight, color } objects
blind Boolean Optional Whether the poll hides others' responses (default: false)
weight Number Optional Poll weight for scoring (default: 1)
tags String[] Optional Associated tags for categorization
studentsAllowedToVote String[] Optional Restrict voting to specific students by email
allowTextResponses Boolean Optional Enables free-text responses (default: false)
allowMultipleResponses Boolean Optional Allow selecting multiple answers (default: false)

Response

Parameter Type Permissions Description
message String Teacher / Mod Success confirmation message

Example Request

// Create a multiple choice poll
const pollData = {
    prompt: "What is your favorite programming language?",
    answers: [
        { answer: "JavaScript", weight: 1.0, color: "#F7DF1E" },
        { answer: "Python", weight: 1.0, color: "#3776AB" },
        { answer: "Java", weight: 1.0, color: "#ED8B00" },
        { answer: "C++", weight: 1.0, color: "#00599C" }
    ],
    blind: false,
    weight: 1,
    tags: ["programming", "languages"],
    allowTextResponses: false,
    allowMultipleResponses: false
};

const response = await fetch('https://formbar.example.com/api/class/456/polls/create', {
    method: 'POST',
    headers: {
        'API': 'your-api-key-here',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(pollData)
});

const result = await response.json();
console.log('Poll creation result:', result);
# Create a multiple choice poll
import requests

headers = {
    'API': 'your-api-key-here',
    'Content-Type': 'application/json'
}

poll_data = {
    'prompt': 'What is your favorite programming language?',
    'answers': [
        {'answer': 'JavaScript', 'weight': 1.0, 'color': '#F7DF1E'},
        {'answer': 'Python', 'weight': 1.0, 'color': '#3776AB'},
        {'answer': 'Java', 'weight': 1.0, 'color': '#ED8B00'},
        {'answer': 'C++', 'weight': 1.0, 'color': '#00599C'}
    ],
    'blind': False,
    'weight': 1,
    'tags': ['programming', 'languages'],
    'allowTextResponses': False,
    'allowMultipleResponses': False
}

response = requests.post(
    'https://formbar.example.com/api/class/456/polls/create',
    headers=headers,
    json=poll_data
)

result = response.json()
print('Poll creation result:', result)

Example Response

{
    "message": "Success"
}

Error Responses

// 403 - Insufficient permissions
{
    "error": "You do not have permission to access this page."
}

// 500 - Server error
{
    "error": "There was a server error try again."
}

Advanced Poll Examples

// Create a blind poll (students can't see others' responses)
const blindPollData = {
    prompt: "Rate the difficulty of today's lesson (1-5)",
    answers: [
        { answer: "1 - Very Easy", weight: 1.0, color: "#00FF00" },
        { answer: "2 - Easy", weight: 1.0, color: "#80FF00" },
        { answer: "3 - Moderate", weight: 1.0, color: "#FFFF00" },
        { answer: "4 - Hard", weight: 1.0, color: "#FF8000" },
        { answer: "5 - Very Hard", weight: 1.0, color: "#FF0000" }
    ],
    blind: true,
    weight: 2  // Double weight for this poll
};

// Create a poll with text responses enabled
const textPollData = {
    prompt: "What topics would you like to cover next week?",
    answers: [
        { answer: "Advanced JavaScript", weight: 1.0, color: "#F7DF1E" },
        { answer: "Database Design", weight: 1.0, color: "#336791" },
        { answer: "API Development", weight: 1.0, color: "#FF6B6B" }
    ],
    allowTextResponses: true,
    allowMultipleResponses: true
};

POST /api/class/{id}/polls/end

Path Parameters

Parameter Type Permissions Description
id Number Teacher / Mod Class ID.

Response

Parameter Type Permissions Description
message String Any 'Success'.

Errors

Status Description
500 { error: string }.

POST /api/class/{id}/polls/clear

Path Parameters

Parameter Type Permissions Description
id Number Teacher / Mod Class ID.

Response

Parameter Type Permissions Description
message String Any 'Success'.

Errors

Status Description
500 { error: string }.

POST /api/class/{id}/polls/response

Path Parameters

Parameter Type Permissions Description
id Number Logged In Class ID.

Body

Parameter Type Required Description
response String Yes Chosen response option.
textRes String Optional Additional text response if enabled.

Response

Parameter Type Permissions Description
message String Any 'Success'.

Errors

Status Description
500 { error: string }.

POST /api/digipogs/award

Body

Parameter Type Required Description
from Number Yes Awarder user ID.
to Number Yes Recipient user ID.
amount Number Yes Amount of digipogs.

Response

Parameter Type Permissions Description
success Boolean Manager / Teacher Indicates success.
message String Any Message response.

Errors

Status Description
400 { success: false, message: string }.
500 { error: string }.

POST /api/digipogs/transfer

Transfers digipogs between users with PIN verification and automatic tax deduction.

Authentication

  • API Key: Include API header with valid key
  • Session: User must be logged in
  • Permission: Student level or higher

Body

Parameter Type Required Description
from Number Yes Sender user ID.
to Number Yes Receiver user ID (can be user ID or pool ID).
amount Number Yes Amount of digipogs to transfer.
pin String Yes 4-6 digit numeric PIN for verification.
reason String Optional Transfer reason/description.

Response

Parameter Type Permissions Description
success Boolean Any Whether transfer succeeded.
message String Any Response message.

Example Request

// Transfer digipogs between users
const transferData = {
    from: 123,
    to: 124,
    amount: 100,
    pin: "1234",
    reason: "Payment for help with assignment"
};

const response = await fetch('https://formbar.example.com/api/digipogs/transfer', {
    method: 'POST',
    headers: {
        'API': 'your-api-key-here',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(transferData)
});

const result = await response.json();
console.log('Transfer result:', result);
# Transfer digipogs between users
import requests

headers = {
    'API': 'your-api-key-here',
    'Content-Type': 'application/json'
}

transfer_data = {
    'from': 123,
    'to': 124,
    'amount': 100,
    'pin': '1234',
    'reason': 'Payment for help with assignment'
}

response = requests.post(
    'https://formbar.example.com/api/digipogs/transfer',
    headers=headers,
    json=transfer_data
)

result = response.json()
print('Transfer result:', result)

Example Response

// Successful transfer
{
    "success": true,
    "message": "Transfer successful. 100 digipogs transferred. 10 digipogs tax applied."
}

Error Responses

// 400 - Invalid PIN
{
    "success": false,
    "message": "Invalid PIN"
}

// 400 - Insufficient funds
{
    "success": false,
    "message": "Insufficient digipogs. You have 50, trying to transfer 100"
}

// 400 - Invalid recipient
{
    "success": false,
    "message": "Recipient not found"
}

// 400 - Invalid amount
{
    "success": false,
    "message": "Amount must be positive"
}

// 500 - Server error
{
    "error": "There was an internal server error. Please try again."
}

Important Notes

  • Tax: 10% tax is automatically deducted and sent to the Formbar Developer Pool (ID: 0)
  • PIN: Must be 4-6 digits, numeric only
  • Pool Transfers: Can transfer directly to digipog pools by using pool ID as to parameter
  • Minimum Transfer: No minimum amount required
  • Maximum Transfer: Limited by sender's available digipogs

GET /api/user/{id}

Path Parameters

Parameter Type Permissions Description
id Number Any User ID.

Response

Parameter Type Permissions Description
id Number Any The user’s unique identifier.
email String Teacher/Manager The user’s email address. Hidden from students and other users without permission.
permissions Number Any The user’s global permission level.
digipogs Number Any The total number of digipogs the user currently holds.
displayName String Any The user’s chosen display name.
verified Boolean Any Whether the user’s account has been verified.

Errors

Status Description
404 { error: 'User not found.' }
500 { error: string }

POST /user/:id/verify

Path Parameters

Parameter Type Permissions Description
id Number Manager User ID to verify.

Response

Parameter Type Permissions Description
message String Manager Success message.

Errors

Status Description
403 Manager permissions required.
404 User not found.
500 Server error.

POST /user/:email/perm

Path Parameters

Parameter Type Permissions Description
email String Manager User email to update.

Body

Parameter Type Required Description
permissions Number Yes New permission level.

Response

Parameter Type Permissions Description
message String Manager Success message.

Errors

Status Description
400 Invalid permissions or missing email.
403 Manager permissions required.
500 Server error.

GET /user/:id/delete

Path Parameters

Parameter Type Permissions Description
id Number Manager User ID to delete.

Response

Parameter Type Permissions Description
message String Manager Success message.

Errors

Status Description
403 Manager permissions required.
404 User not found.
500 Server error.

GET /user/:id/ban

Path Parameters

Parameter Type Permissions Description
id Number Manager User ID to ban.

Response

Parameter Type Permissions Description
message String Manager Success message.

Errors

Status Description
403 Manager permissions required.
404 User not found.
500 Server error.

GET /user/:id/unban

Path Parameters

Parameter Type Permissions Description
id Number Manager User ID to unban.

Response

Parameter Type Permissions Description
message String Manager Success message.

Errors

Status Description
403 Manager permissions required.
404 User not found.
500 Server error.
Clone this wiki locally