Teachify Admin API Mutations

Overview

The Teachify Admin API provides a variety of mutation operations to modify data in your school. These mutations enable you to create, update, and delete resources programmatically, giving you powerful automation capabilities.

Core Concepts

• Input Types: How to structure input data for mutations
• Input Validation: Understanding validation rules and error handling

Available Resources

The API provides mutations for the following resources:

• Courses: Create, update, and delete courses
• Posts: Create, update, and delete posts
• Subscriptions: Manage membership subscriptions
• Students: Provision and manage student accounts
• Assignments: Create and grade assignments
• Events: Manage calendar events
• Send Custom Email: Send custom emails to users

Users vs Students

The Admin API splits user-like operations across two resource groups for a reason:

• The users query returns any user in the school regardless of role (student, teacher, admin), filtered server-side by your filter argument. Use it to list or fetch users.
• The Students mutation group covers the student lifecycle — provisioning new students, and (in the future) updating or off-boarding them. There is intentionally no generic createUser: the admin API only allows creating users with the student role, and the per-role mutation lets us encode role-specific behavior (no welcome email, opportunistic name fill, STUDENT-XXX error codes) without overloading a single field.
• Course-access mutations that involve a student (enrollStudentToCourse, removeStudentFromCourse, expireStudentCourseAccess, extendStudentCourseAccess) live under Courses because the entity being modified is the course’s enrollment, not the student record itself.

Common Patterns

Error Handling

All mutations return an errors field that contains any validation or processing errors:

mutation {
  createCourse(input: { name: "" }) {
    errors {
      field
      message
    }
    course {
      id
      name
    }
  }
}

Response:

{
  "data": {
    "createCourse": {
      "errors": [
        {
          "field": "name",
          "message": "Name cannot be empty"
        }
      ],
      "course": null
    }
  }
}

Input Objects

Most mutations accept a single input parameter containing all required fields:

mutation {
  createCourse(input: {
    name: "Introduction to GraphQL"
    description: "Learn the basics of GraphQL"
    startDate: "2023-06-01"
  }) {
    course {
      id
      name
    }
    errors {
      field
      message
    }
  }
}

Basic Example

Here’s a simple example of creating a new course:

mutation {
  createCourse(input: {
    name: "GraphQL Fundamentals"
    description: "Learn how to use GraphQL APIs"
    published: true
  }) {
    course {
      id
      name
      description
    }
    errors {
      field
      message
    }
  }
}

For detailed information about specific mutations, explore the resource pages linked above.

Authentication

All mutation operations require authentication with an API key. See the Authentication section for details on how to authenticate your requests.

For more information about the Teachify Admin API, please refer to the API Overview.