Skip to content

C0D3R Api Documentation

Jump to bottom
Jasir Zaeem edited this page Jul 12, 2021 · 5 revisions

The c0d3r Discord bot is currently hosted on our CapRover server, it exposes an express Api that can be used to make it perform actions.

Instructions to run bot locally are available in the readme.

Details about the bot's design and arcitecture are available in this design doc

Index

Authorization

All endpoints require an AUTH token beginning with c0d3r: in the Authorization header, you can acquire this from the CapRover server or from engineering, or you can make your own while testing your own local instance of the bot.

Authorization: Bearer TOKEN

Errors

The following errors may be returned by the api as json.

Error Type HTTP Status code Description
auth_error 401 Unauthorized Auth token was invalid or missing.
validation_error 400 Bad Request Some or all request parameters were missing or in an invalid format.
api_error 500 Internal Server Error An error other than the above two occurred, see message for more details.

  • auth_error

An error occurred with authentication.

Status: 400 Bad Request

Fields

  • type: auth_error
  • message: "Access token missing or invalid"

  • validation_error

An error occurred with validation, missing or invalid request body fields.

Status: 500 Internal Server Error

Fields

  • type: "validation_error"
  • message: "One or more fields were missing or invalid."
  • issues: An array of objects, each with a path field which is the path to the invalid field, and message field with details.

  • api_error

An error occurred with api.

Status: 401 Unauthorized

Fields

  • type: "api_error"
  • message: Details about the error

Endpoints

The following endpoints are available

Endpoint Description
POST /api/messages/channel/:channelId Sends a message to a channel
POST /api/messages/lessonChannel/:lessonId Sends a message to a lesson channel by lesson id
POST /api/messages/direct/:userId Sends a direct message to a user
POST /api/submissions/notifications/ Sends a notification for a new submission

  • POST /api/messages/channel/:channelId

Sends a message to a channel.

Takes a discord channel id as the url param and details of the message as json.

Validation Schema

Request body

Field Type Description
message string The content of the message
embed MessageEmbed Optional A discord message embed

Response

Status: 201 Created

Body

Field Type Description
id string The id of the sent message

Examples

cURL

curl 'https://c0d3r.c0d3.com/api/messages/channel/CHANNEL_ID' \
  -H 'authorization: Bearer AUTH_TOKEN' \
  -H 'content-type: application/json' \
  --data-raw '{"message":"YOUR MESSAGE","embed":{"color":39423,"title":"A title","description":"Some description"}}'

JavaScript

fetch('https://c0d3r.c0d3.com/api/messages/channel/CHANNEL_ID', { 
  method: 'post', 
  headers: new Headers({
    'Authorization': 'Bearer AUTH_TOKEN', 
    'Content-Type': 'application/json'
  }), 
  body: JSON.stringify({
    message: 'YOUR MESSAGE',
    embed: {
	color: 0x0099ff,
	title: 'A title',
	description: 'Some description',
    }
  })
});

  • POST /api/messages/lessonChannel/:lessonId

Sends a message to a channel for a lesson by the id of the lesson.

Takes a lessonId as the url param and details of the message as json.

Validation Schema

Request body

Field Type Description
message string The content of the message
embed MessageEmbed Optional A discord message embed

Response

Status: 201 Created

Body

Field Type Description
id string The id of the sent message

Examples

cURL

curl 'https://c0d3r.c0d3.com/api/messages/channel/LESSON_ID' \
  -H 'authorization: Bearer AUTH_TOKEN' \
  -H 'content-type: application/json' \
  --data-raw '{"message":"YOUR MESSAGE","embed":{"color":39423,"title":"A title","description":"Some description"}}'

JavaScript

fetch('https://c0d3r.c0d3.com/api/messages/channel/LESSON_ID', { 
  method: 'post', 
  headers: new Headers({
    'Authorization': 'Bearer AUTH_TOKEN', 
    'Content-Type': 'application/json'
  }), 
  body: JSON.stringify({
    message: 'YOUR MESSAGE',
    embed: {
	color: 0x0099ff,
	title: 'A title',
	description: 'Some description',
    }
  })
});

  • POST /api/messages/direct/:userId

Sends a direct message to a user.

Takes a discord user id as the url param and details of the message as json.

Validation Schema

Request body

Field Type Description
message string The content of the message
embed MessageEmbed Optional A discord message embed

Response

Status: 201 Created

Body

Field Type Description
id string The id of the sent message

Examples

cURL

curl 'https://c0d3r.c0d3.com/api/messages/direct/USER_ID' \
  -H 'authorization: Bearer AUTH_TOKEN' \
  -H 'content-type: application/json' \
  --data-raw '{"message":"YOUR MESSAGE","embed":{"color":39423,"title":"A title","description":"Some description"}}'

JavaScript

fetch('https://c0d3r.c0d3.com/api/messages/direct/USER_ID', { 
  method: 'post', 
  headers: new Headers({
    'Authorization': 'Bearer AUTH_TOKEN', 
    'Content-Type': 'application/json'
  }), 
  body: JSON.stringify({
    message: 'YOUR MESSAGE',
    embed: {
	color: 0x0099ff,
	title: 'A title',
	description: 'Some description',
    }
  })
});

  • POST /api/submissions/notifications/

Sends a notification for a new submission as a formatted embed in the correct channel for the lesson.

Takes details of the submission as json.

Validation Schema

Request body

Field Type Description
idType C0D3 OR DISCORD Whether the supplied id is a c0d3 username or a discord id
id string Id of the submitter, a c0d3 username or a discord id
notificationLessonId string Id of the lesson to send the notification to
lessonId string Id of the lesson the challenge submissions
challengeTitle string Title of the challenge the submission was made for

Response

Status: 201 Created

Body

Field Type Description
id string The id of the sent message

Examples

cURL

curl 'https://c0d3r.c0d3.com/api/submissions/notifications' \
  -H 'authorization: Bearer AUTH_TOKEN' \
  -H 'content-type: application/json' \
  --data-raw '{"idType":"C0D3 OR DISCORD","id":"Student id","notificationLessonId":"Next lesson id","lessonId":"Id of the lesson","challengeTitle":"Title of challenge"}'

JavaScript

fetch('https://c0d3r.c0d3.com/api/submissions/notifications', { 
  method: 'post', 
  headers: new Headers({
    'Authorization': 'Bearer AUTH_TOKEN', 
    'Content-Type': 'application/json'
  }), 
  body: JSON.stringify({
    idType: 'C0D3 OR DISCORD',
    id: 'Student id',
    notificationLessonId: 'Next lesson id',
    lessonId: 'Id of the lesson',
    challengeTitle: 'Title of challenge',
  })
});

Example Notification

image

Clone this wiki locally