Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.1.0
info:
title: Google Classroom API UserProfiles API
version: v1
description: Generated from Google's published Discovery document for Google Classroom API (classroom v1, revision 20261108).
8 operation(s).
contact:
name: Google
url: https://developers.google.com/
termsOfService: https://developers.google.com/terms
externalDocs:
url: https://developers.google.com/workspace/classroom/
servers:
- url: https://classroom.googleapis.com
paths:
/v1/userProfiles/{userId}:
get:
operationId: classroom.userProfiles.get
summary: Get userProfiles
description: 'Returns a user profile. This method returns the following error codes: * `PERMISSION_DENIED` if the requesting
user is not permitted to access this user profile, if no profile exists with the requested ID, or for access errors.'
parameters:
- name: userId
in: path
required: true
description: 'Identifier of the profile to return. The identifier can be one of the following: * the numeric identifier
for the user * the email address of the user * the string literal `"me"`, indicating the requesting user'
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/UserProfile'
4XX:
content: &id001
application/json:
schema:
$ref: '#/components/schemas/GoogleRpcError'
description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
default:
content: *id001
description: Error response (google.rpc.Status)
security:
- oauth2:
- https://www.googleapis.com/auth/classroom.profile.emails
- https://www.googleapis.com/auth/classroom.profile.photos
- https://www.googleapis.com/auth/classroom.rosters
- https://www.googleapis.com/auth/classroom.rosters.readonly
- apiKey: []
tags:
- UserProfiles
/v1/userProfiles/{studentId}/guardianInvitations:
post:
operationId: classroom.userProfiles.guardianInvitations.create
summary: Create guardianInvitations
description: 'Creates a guardian invitation, and sends an email to the guardian asking them to confirm that they are
the student''s guardian. Once the guardian accepts the invitation, their `state` will change to `COMPLETED` and they
will start receiving guardian notifications. A `Guardian` resource will also be created to represent the active guardian.
The request object must have the `student_id` and `invited_email_address` fields set. Failing to set these fields,
or setting any other fields in the request, will result in an error. This method returns the following error codes:
* `PERMISSION_DENIED` if the current user does not have permission to manage guardians, if the guardian in question
has already rejected too many requests for that student, if guardians are not enabled for the domain in question,
or for other access errors. * `RESOURCE_EXHAUSTED` if the student or guardian has exceeded the guardian link limit.
* `INVALID_ARGUMENT` if the guardian email address is not valid (for example, if it is too long), or if the format
of the student ID provided cannot be recognized (it is not an email address, nor a `user_id` from this API). This
error will also be returned if read-only fields are set, or if the `state` field is set to to a value other than `PENDING`.
* `NOT_FOUND` if the student ID provided is a valid student ID, but Classroom has no record of that student. * `ALREADY_EXISTS`
if there is already a pending guardian invitation for the student and `invited_email_address` provided, or if the
provided `invited_email_address` matches the Google account of an existing `Guardian` for this user.'
parameters:
- name: studentId
in: path
required: true
description: ID of the student (in standard format)
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GuardianInvitation'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GuardianInvitation'
4XX:
content: &id002
application/json:
schema:
$ref: '#/components/schemas/GoogleRpcError'
description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
default:
content: *id002
description: Error response (google.rpc.Status)
security:
- oauth2:
- https://www.googleapis.com/auth/classroom.guardianlinks.students
- apiKey: []
tags:
- UserProfiles
get:
operationId: classroom.userProfiles.guardianInvitations.list
summary: List guardianInvitations
description: 'Returns a list of guardian invitations that the requesting user is permitted to view, filtered by the
parameters provided. This method returns the following error codes: * `PERMISSION_DENIED` if a `student_id` is specified,
and the requesting user is not permitted to view guardian invitations for that student, if `"-"` is specified as the
`student_id` and the user is not a domain administrator, if guardians are not enabled for the domain in question,
or for other access errors. * `INVALID_ARGUMENT` if a `student_id` is specified, but its format cannot be recognized
(it is not an email address, nor a `student_id` from the API, nor the literal string `me`). May also be returned if
an invalid `page_token` or `state` is provided. * `NOT_FOUND` if a `student_id` is specified, and its format can be
recognized, but Classroom has no record of that student.'
parameters:
- name: studentId
in: path
required: true
description: 'The ID of the student whose guardian invitations are to be returned. The identifier can be one of the
following: * the numeric identifier for the user * the email address of the user * the string literal `"me"`, indicating
the requesting user * the string literal `"-"`, indicating that results should be returned for all students that
the requesting user is permitted to view guardian invitations.'
schema:
type: string
- name: invitedEmailAddress
in: query
required: false
description: If specified, only results with the specified `invited_email_address` are returned.
schema:
type: string
- name: pageSize
in: query
required: false
description: Maximum number of items to return. Zero or unspecified indicates that the server may assign a maximum.
The server may return fewer than the specified number of results.
schema:
type: integer
format: int32
- name: pageToken
in: query
required: false
description: nextPageToken value returned from a previous list call, indicating that the subsequent page of results
should be returned. The list request must be otherwise identical to the one that resulted in this token.
schema:
type: string
- name: states
in: query
required: false
description: If specified, only results with the specified `state` values are returned. Otherwise, results with a
`state` of `PENDING` are returned.
schema:
type: array
items:
type: string
enum:
- GUARDIAN_INVITATION_STATE_UNSPECIFIED
- PENDING
- COMPLETE
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListGuardianInvitationsResponse'
4XX:
content: &id003
application/json:
schema:
$ref: '#/components/schemas/GoogleRpcError'
description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
default:
content: *id003
description: Error response (google.rpc.Status)
security:
- oauth2:
- https://www.googleapis.com/auth/classroom.guardianlinks.students
- https://www.googleapis.com/auth/classroom.guardianlinks.students.readonly
- apiKey: []
tags:
- UserProfiles
/v1/userProfiles/{studentId}/guardianInvitations/{invitationId}:
patch:
operationId: classroom.userProfiles.guardianInvitations.patch
summary: Patch guardianInvitations
description: 'Modifies a guardian invitation. Currently, the only valid modification is to change the `state` from `PENDING`
to `COMPLETE`. This has the effect of withdrawing the invitation. This method returns the following error codes: *
`PERMISSION_DENIED` if the current user does not have permission to manage guardians, if guardians are not enabled
for the domain in question or for other access errors. * `FAILED_PRECONDITION` if the guardian link is not in the
`PENDING` state. * `INVALID_ARGUMENT` if the format of the student ID provided cannot be recognized (it is not an
email address, nor a `user_id` from this API), or if the passed `GuardianInvitation` has a `state` other than `COMPLETE`,
or if it modifies fields other than `state`. * `NOT_FOUND` if the student ID provided is a valid student ID, but Classroom
has no record of that student, or if the `id` field does not refer to a guardian invitation known to Classroom.'
parameters:
- name: studentId
in: path
required: true
description: The ID of the student whose guardian invitation is to be modified.
schema:
type: string
- name: invitationId
in: path
required: true
description: The `id` field of the `GuardianInvitation` to be modified.
schema:
type: string
- name: updateMask
in: query
required: false
description: 'Mask that identifies which fields on the course to update. This field is required to do an update. The
update fails if invalid fields are specified. The following fields are valid: * `state` When set in a query parameter,
this field should be specified as `updateMask=,,...`'
schema:
format: google-fieldmask
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GuardianInvitation'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GuardianInvitation'
4XX:
content: &id004
application/json:
schema:
$ref: '#/components/schemas/GoogleRpcError'
description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
default:
content: *id004
description: Error response (google.rpc.Status)
security:
- oauth2:
- https://www.googleapis.com/auth/classroom.guardianlinks.students
- apiKey: []
tags:
- UserProfiles
get:
operationId: classroom.userProfiles.guardianInvitations.get
summary: Get guardianInvitations
description: 'Returns a specific guardian invitation. This method returns the following error codes: * `PERMISSION_DENIED`
if the requesting user is not permitted to view guardian invitations for the student identified by the `student_id`,
if guardians are not enabled for the domain in question, or for other access errors. * `INVALID_ARGUMENT` if a `student_id`
is specified, but its format cannot be recognized (it is not an email address, nor a `student_id` from the API, nor
the literal string `me`). * `NOT_FOUND` if Classroom cannot find any record of the given student or `invitation_id`.
May also be returned if the student exists, but the requesting user does not have access to see that student.'
parameters:
- name: studentId
in: path
required: true
description: The ID of the student whose guardian invitation is being requested.
schema:
type: string
- name: invitationId
in: path
required: true
description: The `id` field of the `GuardianInvitation` being requested.
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GuardianInvitation'
4XX:
content: &id005
application/json:
schema:
$ref: '#/components/schemas/GoogleRpcError'
description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
default:
content: *id005
description: Error response (google.rpc.Status)
security:
- oauth2:
- https://www.googleapis.com/auth/classroom.guardianlinks.students
- https://www.googleapis.com/auth/classroom.guardianlinks.students.readonly
- apiKey: []
tags:
- UserProfiles
/v1/userProfiles/{studentId}/guardians/{guardianId}:
delete:
operationId: classroom.userProfiles.guardians.delete
summary: Delete guardians
description: 'Deletes a guardian. The guardian will no longer receive guardian notifications and the guardian will no
longer be accessible via the API. This method returns the following error codes: * `PERMISSION_DENIED` if no user
that matches the provided `student_id` is visible to the requesting user, if the requesting user is not permitted
to manage guardians for the student identified by the `student_id`, if guardians are not enabled for the domain in
question, or for other access errors. * `INVALID_ARGUMENT` if a `student_id` is specified, but its format cannot be
recognized (it is not an email address, nor a `student_id` from the API). * `NOT_FOUND` if the requesting user is
permitted to modify guardians for the requested `student_id`, but no `Guardian` record exists for that student with
the provided `guardian_id`.'
parameters:
- name: studentId
in: path
required: true
description: 'The student whose guardian is to be deleted. One of the following: * the numeric identifier for the
user * the email address of the user * the string literal `"me"`, indicating the requesting user'
schema:
type: string
- name: guardianId
in: path
required: true
description: The `id` field from a `Guardian`.
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Empty'
4XX:
content: &id006
application/json:
schema:
$ref: '#/components/schemas/GoogleRpcError'
description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
default:
content: *id006
description: Error response (google.rpc.Status)
security:
- oauth2:
- https://www.googleapis.com/auth/classroom.guardianlinks.students
- apiKey: []
tags:
- UserProfiles
get:
operationId: classroom.userProfiles.guardians.get
summary: Get guardians
description: 'Returns a specific guardian. This method returns the following error codes: * `PERMISSION_DENIED` if no
user that matches the provided `student_id` is visible to the requesting user, if the requesting user is not permitted
to view guardian information for the student identified by the `student_id`, if guardians are not enabled for the
domain in question, or for other access errors. * `INVALID_ARGUMENT` if a `student_id` is specified, but its format
cannot be recognized (it is not an email address, nor a `student_id` from the API, nor the literal string `me`). *
`NOT_FOUND` if the requesting user is permitted to view guardians for the requested `student_id`, but no `Guardian`
record exists for that student that matches the provided `guardian_id`.'
parameters:
- name: studentId
in: path
required: true
description: 'The student whose guardian is being requested. One of the following: * the numeric identifier for the
user * the email address of the user * the string literal `"me"`, indicating the requesting user'
schema:
type: string
- name: guardianId
in: path
required: true
description: The `id` field from a `Guardian`.
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Guardian'
4XX:
content: &id007
application/json:
schema:
$ref: '#/components/schemas/GoogleRpcError'
description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
default:
content: *id007
description: Error response (google.rpc.Status)
security:
- oauth2:
- https://www.googleapis.com/auth/classroom.guardianlinks.me.readonly
- https://www.googleapis.com/auth/classroom.guardianlinks.students
- https://www.googleapis.com/auth/classroom.guardianlinks.students.readonly
- apiKey: []
tags:
- UserProfiles
/v1/userProfiles/{studentId}/guardians:
get:
operationId: classroom.userProfiles.guardians.list
summary: List guardians
description: 'Returns a list of guardians that the requesting user is permitted to view, restricted to those that match
the request. To list guardians for any student that the requesting user may view guardians for, use the literal character
`-` for the student ID. This method returns the following error codes: * `PERMISSION_DENIED` if a `student_id` is
specified, and the requesting user is not permitted to view guardian information for that student, if `"-"` is specified
as the `student_id` and the user is not a domain administrator, if guardians are not enabled for the domain in question,
if the `invited_email_address` filter is set by a user who is not a domain administrator, or for other access errors.
* `INVALID_ARGUMENT` if a `student_id` is specified, but its format cannot be recognized (it is not an email address,
nor a `student_id` from the API, nor the literal string `me`). May also be returned if an invalid `page_token` is
provided. * `NOT_FOUND` if a `student_id` is specified, and its format can be recognized, but Classroom has no record
of that student.'
parameters:
- name: studentId
in: path
required: true
description: 'Filter results by the student who the guardian is linked to. The identifier can be one of the following:
* the numeric identifier for the user * the email address of the user * the string literal `"me"`, indicating the
requesting user * the string literal `"-"`, indicating that results should be returned for all students that the
requesting user has access to view.'
schema:
type: string
- name: invitedEmailAddress
in: query
required: false
description: Filter results by the email address that the original invitation was sent to, resulting in this guardian
link. This filter can only be used by domain administrators.
schema:
type: string
- name: pageSize
in: query
required: false
description: Maximum number of items to return. Zero or unspecified indicates that the server may assign a maximum.
The server may return fewer than the specified number of results.
schema:
format: int32
type: integer
- name: pageToken
in: query
required: false
description: nextPageToken value returned from a previous list call, indicating that the subsequent page of results
should be returned. The list request must be otherwise identical to the one that resulted in this token.
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListGuardiansResponse'
4XX:
content: &id008
application/json:
schema:
$ref: '#/components/schemas/GoogleRpcError'
description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
default:
content: *id008
description: Error response (google.rpc.Status)
security:
- oauth2:
- https://www.googleapis.com/auth/classroom.guardianlinks.me.readonly
- https://www.googleapis.com/auth/classroom.guardianlinks.students
- https://www.googleapis.com/auth/classroom.guardianlinks.students.readonly
- apiKey: []
tags:
- UserProfiles
components:
securitySchemes:
apiKey:
type: apiKey
in: query
name: key
description: API key; accepted by methods that do not need user data.
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://accounts.google.com/o/oauth2/auth
tokenUrl: https://oauth2.googleapis.com/token
scopes:
https://www.googleapis.com/auth/classroom.student-submissions.me.readonly: View your course work and grades in
Google Classroom
https://www.googleapis.com/auth/classroom.courses: See, edit, create, and permanently delete your Google Classroom
classes
https://www.googleapis.com/auth/classroom.push-notifications: Receive notifications about your Google Classroom
data
https://www.googleapis.com/auth/classroom.coursework.students.readonly: View course work and grades for students
in the Google Classroom classes you teach or administer
https://www.googleapis.com/auth/classroom.announcements: View and manage announcements in Google Classroom
https://www.googleapis.com/auth/classroom.guardianlinks.students.readonly: View guardians for students in your
Google Classroom classes
https://www.googleapis.com/auth/classroom.guardianlinks.students: View and manage guardians for students in your
Google Classroom classes
https://www.googleapis.com/auth/classroom.profile.photos: View the profile photos of people in your classes
https://www.googleapis.com/auth/classroom.coursework.students: Manage course work and grades for students in the
Google Classroom classes you teach and view the course work and grades for classes you administer
https://www.googleapis.com/auth/classroom.addons.teacher: See, create, and update its own attachments to posts
in classes you teach in Google Classroom
https://www.googleapis.com/auth/classroom.courseworkmaterials: See, edit, and create classwork materials in Google
Classroom
https://www.googleapis.com/auth/classroom.profile.emails: View the email addresses of people in your classes
https://www.googleapis.com/auth/classroom.rosters: Manage your Google Classroom class rosters
https://www.googleapis.com/auth/classroom.coursework.me.readonly: View your course work and grades in Google Classroom
https://www.googleapis.com/auth/classroom.topics: See, create, and edit topics in Google Classroom
https://www.googleapis.com/auth/classroom.student-submissions.students.readonly: View course work and grades for
students in the Google Classroom classes you teach or administer
https://www.googleapis.com/auth/classroom.coursework.me: See, create and edit coursework items including assignments,
questions, and grades
https://www.googleapis.com/auth/classroom.rosters.readonly: View your Google Classroom class rosters
https://www.googleapis.com/auth/classroom.addons.student: See and update its own attachments to posts in Google
Classroom
https://www.googleapis.com/auth/classroom.courseworkmaterials.readonly: See all classwork materials for your Google
Classroom classes
https://www.googleapis.com/auth/classroom.announcements.readonly: View announcements in Google Classroom
https://www.googleapis.com/auth/classroom.courses.readonly: View your Google Classroom classes
https://www.googleapis.com/auth/classroom.guardianlinks.me.readonly: View your Google Classroom guardians
https://www.googleapis.com/auth/classroom.topics.readonly: View topics in Google Classroom
schemas:
Empty:
description: 'A generic empty message that you can re-use to avoid defining duplicated empty messages in your APIs.
A typical example is to use it as the request or the response type of an API method. For instance: service Foo { rpc
Bar(google.protobuf.Empty) returns (google.protobuf.Empty); }'
type: object
properties: {}
GlobalPermission:
properties:
permission:
type: string
description: Permission value.
enum:
- PERMISSION_UNSPECIFIED
- CREATE_COURSE
type: object
description: Global user permission description.
GoogleRpcError:
type: object
description: The error envelope every Google API returns.
properties:
error:
type: object
properties:
code:
type: integer
message:
type: string
status:
type: string
details:
type: array
items:
type: object
Guardian:
description: Association between a student and a guardian of that student. The guardian may receive information about
the student's course work.
type: object
properties:
studentId:
description: Identifier for the student to whom the guardian relationship applies.
type: string
invitedEmailAddress:
description: The email address to which the initial guardian invitation was sent. This field is only visible to
domain administrators.
type: string
guardianProfile:
$ref: '#/components/schemas/UserProfile'
description: User profile for the guardian.
guardianId:
type: string
description: Identifier for the guardian.
GuardianInvitation:
properties:
state:
enum:
- GUARDIAN_INVITATION_STATE_UNSPECIFIED
- PENDING
- COMPLETE
type: string
description: The state that this invitation is in.
invitationId:
description: Unique identifier for this invitation. Read-only.
type: string
invitedEmailAddress:
type: string
description: Email address that the invitation was sent to. This field is only visible to domain administrators.
creationTime:
description: The time that this invitation was created. Read-only.
format: google-datetime
type: string
studentId:
description: ID of the student (in standard format)
type: string
description: An invitation to become the guardian of a specified user, sent to a specified email address.
type: object
ListGuardianInvitationsResponse:
properties:
guardianInvitations:
type: array
items:
$ref: '#/components/schemas/GuardianInvitation'
description: Guardian invitations that matched the list request.
nextPageToken:
description: Token identifying the next page of results to return. If empty, no further results are available.
type: string
description: Response when listing guardian invitations.
type: object
ListGuardiansResponse:
properties:
nextPageToken:
description: Token identifying the next page of results to return. If empty, no further results are available.
type: string
guardians:
type: array
items:
$ref: '#/components/schemas/Guardian'
description: Guardians on this page of results that met the criteria specified in the request.
description: Response when listing guardians.
type: object
Name:
properties:
fullName:
description: The user's full name formed by concatenating the first and last name values. Read-only.
type: string
givenName:
type: string
description: The user's first name. Read-only.
familyName:
type: string
description: The user's last name. Read-only.
description: Details of the user's name.
type: object
UserProfile:
description: Global information for a user.
properties:
photoUrl:
type: string
description: URL of user's profile photo. Must request `https://www.googleapis.com/auth/classroom.profile.photos`
scope for this field to be populated in a response body. Read-only.
emailAddress:
type: string
description: Email address of the user. Must request `https://www.googleapis.com/auth/classroom.profile.emails`
scope for this field to be populated in a response body. Read-only.
permissions:
items:
$ref: '#/components/schemas/GlobalPermission'
type: array
description: Global permissions of the user. Read-only.
verifiedTeacher:
type: boolean
description: Represents whether a Google Workspace for Education user's domain administrator has explicitly verified
them as being a teacher. This field is always false if the user is not a member of a Google Workspace for Education
domain. Read-only
id:
type: string
description: Identifier of the user. Read-only.
name:
$ref: '#/components/schemas/Name'
description: Name of the user. Read-only.
type: object
x-provenance:
method: harvested
publisher: Google
source: https://classroom.googleapis.com/$discovery/rest?version=v1
note: converted by discovery-to-openapi.py from Google's Discovery document (revision 20261108)