API Reference

API Reference

This document provides a comprehensive reference for all API endpoints in the University Polling API.

Authentication

All endpoints require authentication using one of the following methods:

• OAuth2 Password Flow
  • Token URL: auth/jwt/login
• API Key (Cookie)
  • Parameter Name: fastapiusersauth, in: cookie

Base URL

All API requests should be made to your API server base URL.

Endpoints Overview

Workspaces

• GET /workspaces - Get all workspaces for current user
• POST /workspaces - Create a new workspace
• GET /workspaces/permissions - Get all workspace permissions
• GET /workspaces/{workspace_id} - Get workspace details
• PATCH /workspaces/{workspace_id} - Update workspace
• DELETE /workspaces/{workspace_id} - Delete workspace

Workspace Members

• GET /workspaces/{workspace_id}/members - Get workspace members
• POST /workspaces/{workspace_id}/members - Add members to workspace
• DELETE /workspaces/{workspace_id}/members/{account_id} - Remove member

Workspace Groups

• GET /workspaces/{workspace_id}/groups - Get workspace groups
• POST /workspaces/{workspace_id}/groups - Create group in workspace

Workspace Policies

• GET /workspaces/{workspace_id}/policies - Get workspace policies
• PUT /workspaces/{workspace_id}/policies/{policy_id} - Update workspace policy

Workspace Polls

• GET /workspaces/{workspace_id}/polls - Get workspace polls
• POST /workspaces/{workspace_id}/polls - Create poll in workspace

Groups

• GET /groups/ - Get all groups (with filters)
• POST /groups/ - Create a new group
• GET /groups/permissions - Get all group permissions
• GET /groups/{group_id} - Get group details
• PATCH /groups/{group_id} - Update group
• DELETE /groups/{group_id} - Delete group

Group Members

• GET /groups/{group_id}/members - Get group members
• POST /groups/{group_id}/members - Add members to group
• DELETE /groups/{group_id}/members/{account_id} - Remove member from group

Group Policies

• GET /groups/{group_id}/policies - Get group policies
• PUT /groups/{group_id}/policies/{policy_id} - Update group policy

Polls

• GET /polls/{poll_id} - Get poll details
• PATCH /polls/{poll_id} - Update poll
• DELETE /polls/{poll_id} - Delete poll
• GET /polls/{poll_id}/questions - Get poll questions
• GET /polls/{poll_id}/policies - Get poll policies

Accounts

• GET /accounts - Get all accounts
• GET /accounts/me - Get current user account
• PATCH /accounts/me - Update current user account
• DELETE /accounts/me - Delete current user account
• GET /accounts/{id} - Get user account by ID
• PATCH /accounts/{id} - Update user account by ID
• DELETE /accounts/{id} - Delete user account by ID

Common Response Codes

• 200 OK - Request successful
• 201 Created - Resource created successfully
• 204 No Content - Request successful, no content returned
• 400 Bad Request - Invalid request data
• 401 Unauthorized - Authentication required
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 422 Unprocessable Entity - Validation error

Example Requests

Create Workspace

POST /workspaces
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "name": "My Workspace",
  "description": "This is my workspace"
}

Get Workspace with Groups and Members

GET /workspaces/64f7a1b8e1f1d5f5f5b4f8e1?include=groups&include=members
Authorization: Bearer <access_token>

Update User Permissions

PUT /workspaces/64f7a1b8e1f1d5f5f5b4f8e1/policies/64f7a1b8e1f1d5f5f5b4f8e2
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "permissions": ["get_workspace", "get_members", "add_members"]
}

For complete API specifications with detailed request/response schemas, refer to the interactive documentation available at /docs when your server is running.