Base URL

All API requests use the following base URL:

Development

https://classbuddy-backend-dev.redbayf6dbaeae.northcentralus.azurecontainerapps.io

Authentication

All endpoints require Bearer token authentication:

Authorization: Bearer <jwt-token>

Common Headers

Include these headers in all requests:

Authorization: Bearer <jwt-token>
Content-Type: application/json

HTTP Methods

Standard Response Codes

Pagination Patterns

Page-Based Pagination

Used by: list_users, list_group, list_vta

{
  "page": 1,
  "limit": 10
}

Response includes:

{
  "current_page": 1,
  "next_page": 2,
  "total_pages": 5,
  "total_records": 47
}

Offset-Based Pagination

Used by: list_group_users

{
  "offset": 0,
  "group_id": 1000385
}

Increment offset by the number of returned results.

Continuation Token Pagination

Used by: list_agents

{
  "list_agents_continuation_token": null
}

Use returned token for next page:

{
  "list_agents_continuation_token": "token-from-previous-response"
}

Common Parameters

User Identification

• email_address (string): User's email

• user_ids (array): List of user emails

• user_role (integer): 1=Student, 2=Instructor, 3=Admin

Group Identification

• group_id (integer): Unique group identifier

• group_ids (array): List of group IDs

• group_name (string): Group name

• global_group (integer): 0=local, 1=global

Agent Identification

• agent_id (string): Unique agent identifier

• agent_type (string): "vta" or "my_agent"

• agent_name (string): Agent name

Quick Reference

Authentication Flow

1. Run Azure AD script → Get Azure AD token
2. POST /api/v1/login → Get JWT token
3. Use JWT token in all API calls

User Management

POST /api/v1/invite_users/         # Invite new user
POST /api/v1/list_users/           # List all users
POST /api/v1/delete_user           # Delete user

Group Management

POST /api/v1/create_group/         # Create group
POST /api/v1/list_group            # List groups
GET  /api/v1/groups?search_term=X  # Search groups
POST /api/v1/delete_group          # Delete group

Group Membership

POST /api/v1/add_users_to_group       # Add users
POST /api/v1/remove_users_from_group  # Remove users
POST /api/v1/list_group_users         # List members

Agent Operations

POST /api/v1/list_agents              # List agents
POST /api/v1/list_vta                 # List VTAs
POST /api/v1/get_vta_details          # Get VTA config
POST /api/v1/add_agent_to_group       # Grant access
POST /api/v1/remove_agent_from_group  # Revoke access

Example Request Template

curl -X POST "https://<baseURL>/api/v1/<endpoint>" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "parameter": "value"
  }'

Rate Limiting

• Implement retry logic with exponential backoff

• Avoid excessive rapid requests

• Cache responses when appropriate

• Batch operations when possible

Error Handling

Check Status Codes

if [ $status_code -eq 401 ]; then
  # Re-authenticate
fi

Parse Error Messages

{
  "detail": "Error description"
}

Common Issues

401 Unauthorized:

• Token expired → Re-authenticate

• Token missing → Add Authorization header

• Wrong token type → Use JWT token, not Azure AD token

404 Not Found:

• User not in database → Invite user first

• Invalid ID → Verify IDs exist

400 Bad Request:

• Missing required fields

• Invalid parameter values

• Incorrect data types

Best Practices

1. Store tokens securely: Never commit tokens to code

2. Implement token refresh: Handle expired tokens gracefully

3. Use HTTPS: All requests must use encrypted connections

4. Validate input: Check parameters before sending requests

5. Handle errors: Implement proper error handling and logging

6. Batch operations: Group related operations together

7. Cache strategically: Reduce API calls with appropriate caching

Testing Endpoints

Quick Test

# Set base URL
BASE_URL="https://classbuddy-backend-dev.redbayf6dbaeae.northcentralus.azurecontainerapps.io"
JWT_TOKEN="your-jwt-token"

# Test authentication
curl -X GET "$BASE_URL/api/v1/login" \
  -H "Authorization: Bearer $AZURE_TOKEN"

# Test list users
curl -X POST "$BASE_URL/api/v1/list_users/" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "limit": 5}'

API Versioning

Current version: /api/v1/

All endpoints include version in the path.