Standard Response Structure

CampusMindAI APIs follow consistent response patterns across endpoints.

Success Responses

Simple Success

{
  "success": true
}

Used by: delete_user

Message Response

{
  "message": "success"
}

Used by: add_users_to_group, remove_users_from_group

Data Response

{
  "data": {
    // Resource data
  }
}

Used by: get_vta_details

ID Response

{
  "agent_id": "asst_abc123",
  "group_id": 1000385
}

Used by: add_agent_to_group, create_group

Pagination Response Formats

Page-Based Pagination

{
  "current_page": 1,
  "next_page": 2,
  "total_pages": 5,
  "total_records": 47,
  "limit": 10,
  "users": [...]
}

Fields:

• current_page: Current page number

• next_page: Next page (0 if last page)

• total_pages: Total available pages

• total_records: Total items across all pages

• limit: Items per page

Used by: list_users, list_group, list_vta, search_groups

Offset-Based Pagination

{
  "offset": 0,
  "limit": 50,
  "users": [...],
  "group_id": 1000385
}

Fields:

• offset: Starting position

• limit: Number of items returned

Used by: list_group_users

Continuation Token Pagination

{
  "agents": [...],
  "list_agents_continuation_token": "token-abc123"
}

Fields:

• list_agents_continuation_token: Token for next page (null if last page)

Used by: list_agents

Resource Objects

User Object

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_name": "John Doe",
  "user_email": "john.doe@example.com",
  "user_create_at": "2024-01-15T10:30:00Z",
  "user_groups": ["Engineering", "Admins"],
  "user_role": 3,
  "user_invited_by": "admin@example.com"
}

Group Object

{
  "group_id": 1000385,
  "group_name": "CS101_Fall2024",
  "group_description": "Introduction to Computer Science - Fall 2024",
  "group_updated_at": "2024-12-02T10:30:00Z",
  "group_tenant_global": "0",
  "group_created_by": "admin@example.com",
  "group_created_by_id": "550e8400-e29b-41d4-a716-446655440000",
  "role_id": 1
}

Agent Object

{
  "agent_id": "asst_abc123",
  "agent_name": "Research Assistant",
  "agent_description": "Helps with research",
  "agent_type": "my_agent",
  "agent_active": 1,
  "agent_publish_marketplace": 1,
  "agent_category": ["Research"],
  "agent_access": ["groups"],
  "user_email": "creator@example.com"
}

VTA Object

{
  "vta_id": "asst_XN5v91U6aVRS0r0pJHc6zN18",
  "vta_basics": {
    "vta_name": "CS101_VTA",
    "vta_course_name": "Introduction to Computer Science"
  },
  "vta_published": 1,
  "vta_active": 1,
  "conversations": 342
}

Error Response Formats

Standard Error

{
  "detail": "Error description"
}

Example:

{
  "detail": "User not found."
}

Validation Error

{
  "detail": [
    {
      "loc": ["body", "email_address"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Authentication Error

{
  "detail": "Not authenticated"
}

Common Field Types

Timestamps

All timestamps use ISO 8601 format:

2024-12-02T10:30:00Z

Boolean as Integer

Many boolean fields use integers:

• 0 = false/disabled/inactive

• 1 = true/enabled/active

Examples:

• agent_active: 1 (active)

• vta_published: 0 (not published)

• global_group: 1 (global)

Arrays

Empty vs null arrays:

{
  "user_groups": null,        // No groups assigned
  "user_groups": [],          // Empty group list
  "user_groups": ["Group1"]   // Has groups
}

Role IDs

Standard role values:

• 1 = Student

• 2 = Instructor

• 3 = Administrator

Response Patterns by Operation

Create Operations

Request: Create new resource Response: Created resource with ID

{
  "group_data": {
    "group_id": 1000385,
    "group_name": "New Group",
    // ... other fields
  }
}

List Operations

Request: Get multiple resources Response: Array with pagination

{
  "current_page": 1,
  "total_records": 47,
  "users": [...]
}

Delete Operations

Request: Remove resource Response: Success indicator

{
  "success": true
}

or

{
  "group_id": 0
}

Note: 0 or empty string often indicates successful deletion.

Update Operations

Request: Modify resource Response: Updated resource data

{
  "agent_id": "asst_abc123"
}

Parsing Responses

Check Status Code First

if response.status_code == 200:
    data = response.json()
else:
    handle_error(response)

Handle Different Pagination Types

# Page-based
if "next_page" in data and data["next_page"] > 0:
    fetch_next_page(data["next_page"])

# Continuation token
if data["list_agents_continuation_token"]:
    fetch_next(data["list_agents_continuation_token"])

# Offset-based
if len(data["users"]) == data["limit"]:
    fetch_next(offset + limit)

Extract Resource Lists

users = response.json().get("users", [])
groups = response.json().get("groups", [])
agents = response.json().get("agents", [])

Empty Results

Empty List vs Error

Empty list (valid):

{
  "current_page": 1,
  "total_records": 0,
  "users": []
}

Error:

{
  "detail": "Not found"
}

Best Practices

1. Always check status code before parsing JSON

2. Handle null values appropriately

3. Validate pagination fields before requesting next page

4. Parse timestamps using ISO 8601 parsers

5. Check for detail field in error responses

6. Handle empty arrays vs null values differently

7. Verify expected fields exist before accessing

Response Validation

Expected Fields

Before accessing fields, verify they exist:

if "users" in response and isinstance(response["users"], list):
    process_users(response["users"])

Type Checking

# Check integer fields
if isinstance(data.get("user_role"), int):
    role = data["user_role"]

# Check string fields
if isinstance(data.get("email_address"), str):
    email = data["email_address"]