Skip to main content

​
Overview

The Invitation API allows channel editors to invite other users to collaborate on channels. Invitations can be accepted, declined, or revoked, and support both edit and view-only access modes.

​
Base Endpoint

GET /api/invitation/

​
Authentication

All Invitation API endpoints require authentication. Users can only view and manage invitations they have sent or received.

​
Invitation Object

The Invitation object contains the following fields:
​
id
string
required
Unique identifier for the invitation (UUID)
​
email
string
required
Email address of the invited user (max 100 characters)
​
channel
string
required
ID of the channel to which the user is invited
​
channel_name
string
Name of the channel (read-only)
​
share_mode
string
required
Access level for the invitation: "edit" or "view"
​
first_name
string
First name of the invited user (max 100 characters, optional)
​
last_name
string
Last name of the invited user (max 100 characters, optional)
​
accepted
boolean
Whether the invitation has been accepted (default: false)
​
declined
boolean
Whether the invitation has been declined (default: false)
​
revoked
boolean
Whether the invitation has been revoked by the sender (default: false)
​
sender_name
string
Full name of the user who sent the invitation (read-only)

​
List Invitations

Retrieve invitations sent to or by the authenticated user. 
GET /api/invitation/

​
Query Parameters

​
invited
string
Filter invitations sent to the authenticated user’s email address
​
channel
string
Filter invitations by channel ID

​
Example Request

curl -X GET "https://studio.learningequality.org/api/invitation/?channel=abc123" \
  -H "Authorization: Token YOUR_AUTH_TOKEN"

​
Example Response

[
  {
    "id": "inv123-4567-8901-abcd",
    "email": "[email protected]",
    "channel": "abc123",
    "channel_name": "Mathematics Course",
    "share_mode": "edit",
    "first_name": "John",
    "last_name": "Doe",
    "accepted": false,
    "declined": false,
    "revoked": false,
    "sender_name": "Jane Smith"
  }
]

​
Create Invitation

Invite a user to collaborate on a channel. 
POST /api/invitation/

​
Request Body

​
email
string
required
Email address of the user to invite
​
channel
string
required
ID of the channel to share
​
share_mode
string
required
Access level: "edit" for edit access or "view" for view-only access
​
first_name
string
First name of the invited user (optional)
​
last_name
string
Last name of the invited user (optional)

​
Example Request

curl -X POST "https://studio.learningequality.org/api/invitation/" \
  -H "Authorization: Token YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "channel": "abc123",
    "share_mode": "edit",
    "first_name": "John",
    "last_name": "Doe"
  }'

​
Example Response

{
  "id": "inv123-4567-8901-abcd",
  "email": "[email protected]",
  "channel": "abc123",
  "share_mode": "edit",
  "first_name": "John",
  "last_name": "Doe",
  "accepted": false,
  "declined": false,
  "revoked": false
}

​
Accept Invitation

Accept an invitation to collaborate on a channel. 
POST /api/invitation/{id}/accept/

​
Path Parameters

​
id
string
required
ID of the invitation to accept

​
Example Request

curl -X POST "https://studio.learningequality.org/api/invitation/inv123-4567-8901-abcd/accept/" \
  -H "Authorization: Token YOUR_AUTH_TOKEN"

​
Example Response

{
  "status": "success"
}
When an invitation is accepted:
  • If share_mode is "edit", the user is added to the channel’s editors
  • If share_mode is "view", the user is added to the channel’s viewers
  • The invitation’s accepted field is set to true

​
Decline Invitation

Decline an invitation to collaborate on a channel. 
POST /api/invitation/{id}/decline/

​
Path Parameters

​
id
string
required
ID of the invitation to decline

​
Example Request

curl -X POST "https://studio.learningequality.org/api/invitation/inv123-4567-8901-abcd/decline/" \
  -H "Authorization: Token YOUR_AUTH_TOKEN"

​
Example Response

{
  "status": "success"
}

​
Update Invitation

Update an invitation (revoke or modify fields). 
PATCH /api/invitation/{id}/

​
Path Parameters

​
id
string
required
ID of the invitation to update

​
Request Body

​
revoked
boolean
Set to true to revoke the invitation (only available to sender)
​
accepted
boolean
Set to true to accept the invitation (only available to invited user, cannot be set if revoked)
​
declined
boolean
Set to true to decline the invitation (only available to invited user)

​
Example Request (Revoke)

curl -X PATCH "https://studio.learningequality.org/api/invitation/inv123-4567-8901-abcd/" \
  -H "Authorization: Token YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "revoked": true
  }'

​
Permissions

Invitation access is controlled as follows:
  • Create: User must have edit access to the channel
  • View: User can view invitations they sent or received, or for channels they edit
  • Accept/Decline: Only the invited user can accept or decline (cannot accept if revoked)
  • Revoke: Only the sender can revoke an invitation

​
Access Modes

​
edit
Full edit access to the channel. User can create, modify, and delete content.
​
view
View-only access to the channel. User can browse content but cannot make changes.

​
Error Responses

​
400 Bad Request
Invalid request parameters, missing required fields, or user attempting to accept a revoked invitation
​
401 Unauthorized
Missing or invalid authentication token
​
403 Forbidden
User does not have permission to create, modify, or accept the invitation
​
404 Not Found
Invitation or channel not found

Build docs developers (and LLMs) love

Get started for freeTalk to us