Gradescope API

Documentation for the Gradescope submission module.

Overview

The gradescope.js module handles all communication with the Gradescope API.

Main Function

submitAssg()

Submit code to a Gradescope assignment.

import { submitAssg } from './gradescope.js';

const result = await submitAssg(
  code,       // string - The code to submit
  course_id,  // string - Gradescope course ID
  stud_id,    // string - Student ID (optional)
  asg_id,     // string - Assignment ID
  file_name,  // string - Filename for submission
  token,      // string - Gradescope authenticity token
  cookie      // string - Gradescope session cookie
);

Parameters

Parameter	Type	Required	Description
code	string	Yes	Python code to submit
course_id	string	Yes	Gradescope course ID
stud_id	string	No	Student ID
asg_id	string	Yes	Assignment ID
file_name	string	Yes	Filename (e.g., program.py)
token	string	Yes	CSRF authenticity token
cookie	string	Yes	Session cookie

Return Value

{
  success: true,
  url: "https://www.gradescope.com/courses/.../submissions/..."
}

Or on error:

{
  success: false,
  error: "Error message"
}

How It Works

1. Create File Blob

const blob = new Blob([code], { type: 'text/x-python' });

2. Build FormData

const formData = new FormData();
formData.append('submission[files][]', blob, file_name);
formData.append('authenticity_token', token);

3. Submit to Gradescope

const response = await fetch(
  `https://www.gradescope.com/courses/${course_id}/assignments/${asg_id}/submissions`,
  {
    method: 'POST',
    headers: {
      'Cookie': cookie
    },
    body: formData
  }
);

Gradescope API Details

Submission URL

POST https://www.gradescope.com/courses/{course_id}/assignments/{asg_id}/submissions

Required Headers

Header	Value
Cookie	Session cookie from Gradescope
Content-Type	multipart/form-data (set automatically)

Required Form Fields

Field	Description
submission[files][]	The code file
authenticity_token	CSRF token

Getting Credentials

Authenticity Token

The CSRF token can be found:

1. In the page source of any Gradescope form
2. In form data when submitting manually
3. In the <meta name="csrf-token"> tag

Session Cookie

The session cookie is set when you log into Gradescope. It typically includes:

• _gradescope_session
• signed_token (sometimes)

Error Handling

Common Errors

Error	Cause	Solution
401 Unauthorized	Invalid/expired cookie	Refresh credentials
403 Forbidden	Invalid CSRF token	Get new token
404 Not Found	Invalid course/assignment ID	Check IDs
422 Unprocessable	Invalid submission format	Check file format

Example Error Handling

try {
  const result = await submitAssg(...);
  if (!result.success) {
    console.error('Submission failed:', result.error);
  }
} catch (error) {
  console.error('Network error:', error);
}

Security Considerations

1. Never expose credentials — TOKEN and COOKIE are server-side only
2. Use HTTPS — All Gradescope communication is encrypted
3. Rotate credentials — Update when they expire
4. Don't log credentials — Avoid logging sensitive values

Testing

Mock Submission

For testing without hitting Gradescope:

// In test environment
if (process.env.NODE_ENV === 'test') {
  return {
    success: true,
    url: 'https://gradescope.com/mock/submission'
  };
}

Verify Credentials

// Quick test that credentials work
const testResult = await submitAssg(
  'print("test")',
  process.env.COURSE_ID,
  '',
  'TEST_ASSIGNMENT_ID',
  'test.py',
  process.env.TOKEN,
  process.env.COOKIE
);