Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/codio/codio-api-js


https://github.com/codio/codio-api-js

Last synced: 5 months ago
JSON representation

Awesome Lists containing this project

README 

          
# codio-api-js

```

import codio from 'codio-api-js'



codio.v1.setDomain('codio.com') // codio.co.uk for UK domain, codio.com is default

```



Follow https://docs.codio.com/develop/develop/ide/tools/ghapi.html#api-integration-information to generate

API keys.

## Requirements

- Nodejs

- zstd



## How to build

- Run `yarn`

- Run `yarn build`



## Authentication

```

const token = await codio.v1.auth(client_id, client_secret)

```



The token is saved inside the library all consequence calls will be made using the token.



## API rate limit



Burst rate limit: 50 requests per 10 seconds per organization



Daily limit: 10.000 requests per organization



API specific HTTP headers:



| Header | Description |

|----------|----------|

| X-RateLimit-Limit | Number of request for burst, Example 50 |

| X-RateLimit-Remaining | Number of requests left for the time window, Example 34 |

| X-RateLimit-Reset | The remaining window before the rate limit resets in UTC epoch seconds |

| X-RateLimit-DailyLimit | Number of request per day, Example 10000 |

| X-RateLimit-DailyLimit-Remaining | Number of request per day remaining, Example 3456 |



## Publish Assignment

These methods allow to publish the assignment either as archive (zip and tar.gz is supported)

you need to specify `course Id : string`, `assignmentId: string`, `changelog: string` and path to either project folder or archive

```

  await codio.v1.assignment.publish(courseId, assignmentId, projectPath,

   {changelog: string, stack: string, withStackUpdate: boolean} || changelog: string))



  await codio.v1.assignment.publishArchive(courseId, assignmentId, projectArchivePath,

   {changelog: string, stack: string, withStackUpdate: boolean} || changelog: string))

   

  stack - stackVersionId || stackVersionId:latest



```



GitHub Action: https://github.com/codio/codio-assignment-publish-action

GitHub Action Usage Example: https://github.com/ksimuk/codio-test-publish/blob/master/.github/workflows/publish.yaml



## Reduce (ex Books)

Truncate pages from project. This method creates in the `dstDir` reduced version of the project, 

which contains only pages specified in `sections: string[]` and files specified in `paths: string[]`

```

  await codio.v1.tools.reduce(srcDir, dstDir, sections, paths, sectionsConfig)

```



## Reduce Publish

Similar to reduce but publishes generated projects as assignments.

```

  await codio.v1.assignment.reducePublish(courseId, srcDir, yamConfigsDir,

   {changelog: string, stack: string, withStackUpdate: boolean} || changelog: string))

```

`yamlConfig` Directory should contain yaml files in the next format:

`assignment` - id of the assignment to publish

`assignmentName` - or name of the assignment to publish

`section` - section name or array of paths to the section

`paths` - an array of files that needs to be exported, `.guides` is exported fully to all assignments

`withChildren` - boolean - preserve children structure, `true` by default



```

- assignment: 

  section:  ["Chapter 1", "Section 1.1"]

  paths: ['Section1.java'] 

  

- assignment: 

  section:  Section 3



- assignmentName: 

  section: Section 1



- assignmentName: 

  section: Section 2

  withChildren: false



```



GitHub Action: https://github.com/codio/codio-assignment-publish-action

GitHub Action Usage Example: https://github.com/ksimuk/codio-test-publish-book/tree/master/.github



## Assessment Library



### List Libraries



Returns an array of `Library` items

```

  Library = {

    name: string

    id: string

    createdBy: string

  }



  const libraries = await codio.v1.assessment.listLibraries()

```



### Find Assessments in a library



Returns an array of `Assessment` items

```

  const assessments = await codio.v1.assessment.find('libraryId || name', searchTags: Map)

```



### Synchronize assessments from library



Publishes all assessments from the project in `project_path` to the library

```

  await codio.v1.assessment.fromCodioProject('libraryId || name', '')

```



Please be aware on that this action will update {assessment_id}.json files with new tags 

needed to keep connection between project assessment and library item. You will 

need to commit the changes to avoid duplication the assessment



GitHub action: https://github.com/codio/codio-assessments-publish-action



### Get Course Info



#### Course assignments



return 



```

  await codio.v1.course.info(courseId)

```

return `Course` object

```

Course = {

  id: string,

  name: string,

  description?: string,

  modules: Module[],

  assignments: Assignment[],

  creationDate: Date,

  archivedDate: Date,

  archived: boolean,

  start?: Date,

  end?: Date,

  timezone?: string,

  tags?: string[]

}

Module = {

  id: string,

  name: string,

  assignments: Assignment[]

}

Assignment = {

  id: string,

  name: string

}

```



### Course info by name



return



```

  await codio.v1.course.findByName(courseName, withHiddenAssignments)

```

return `Course` object

```

Course = {

  id: string,

  name: string,

  description?: string,

  modules: Module[],

  assignments: Assignment[],

  creationDate: Date,

  archivedDate: Date,

  archived: boolean,

  start?: Date,

  end?: Date,

  timezone?: string,

  tags?: string[]

}

Module = {

  id: string,

  name: string,

  assignments: Assignment[]

}

Assignment = {

  id: string,

  name: string

}

```



#### Course assignments student Progress



```

  await codio.v1.course.assignmentStudentsProgress(courseId, assignmentId)

```

returns `StudentProgress[]` object 

```

StudentProgress = {

  student_id: string

  student_email: string

  seconds_spent: number

  grade: number

  extra_credit: number

  status: string

  completion_date: Date

  extendedDeadline: number

  extendedTimeLimit: number

}

```



#### Course student Progress



```

  await codio.v1.course.studentCourseProgress(courseId, studentId|email|login)

```

returns `AssignmentProgress[]` object

```

AssignmentProgress = {

  assignment_name: string

  assignment_id: string

  module_name: string

  module_id: string

  started: boolean

  progress: {

    seconds_spent: number

    grade: number

    status: string

    completion_date: Date

    extended_deadline: number

    extended_time_limit: number

  }

}

```



#### Course assignments students projects



Prepare student's project 

you need to specify `course Id : string`, `assignmentId: string`, `studentId: string`



```

  await codio.v1.course.exportStudentAssignment(courseId, assignmentId, studentId)

```

returns `archive url` string



Or download student's project

you need to specify `course Id : string`, `assignmentId: string`, `studentId: string`



```

  await codio.v1.course.downloadStudentAssignment(courseId, assignmentId, studentId, filePath)

```

downloads file to filePath



#### Course users



Fetch course students excepts test users



```

  await codio.v1.course.getStudents(courseId)

```

returns user `User[]` object



```

User = {

  id: string

  name: string

  login: string

  email: string

}

```



Fetch course teachers



```

  await codio.v1.course.getTeachers(courseId)

```

returns user `User[]` object



Add teacher to course



```

  await codio.v1.course.addTeacher(courseId, userId, readOnly?)

```

- `readOnly` (optional, default `false`): when `true`, the user is added as a read‑only teacher.

- returns `boolean` — true if the teacher was successfully added



Example:

```javascript

// Add full teacher (default)

await codio.v1.course.addTeacher(courseId, userId)



// Add read-only teacher

await codio.v1.course.addTeacher(courseId, userId, true)

```



#### Course management



Create course



```

  await codio.v1.course.createCourse(courseData)

```

Parameters:

```

CreateCourseRequest = {

  name: string,

  description?: string,

  start?: string,

  end?: string,

  timezone?: string,

  tags?: string[]

}

```

Notes:

- `start` and `end` are ISO 8601 strings (e.g., `2025-09-01T13:00:00Z`).

- `timezone` should be an IANA timezone name (e.g., `America/New_York`).

- In responses, `Course.start` is a `Date` (or absent), while `CreateCourseRequest.start` is a string.

returns `string` — newly created courseId



Example:

```javascript

const courseId = await codio.v1.course.createCourse({

  name: 'Intro to CS',

  description: 'Fall 2025 section',

  start: '2025-09-01T13:00:00Z', // ISO 8601 string

  end: '2025-12-20T23:59:59Z',   // ISO 8601 string

  timezone: 'America/New_York',

  tags: ['CS101','Fall-2025']

})

```



Create module



```

  await codio.v1.course.createModule(courseId, moduleName)

```

returns `string` — newly created moduleId



Example:

```javascript

const moduleId = await codio.v1.course.createModule(courseId, 'Module 1: Basics')

```



#### Export student CSV



Returns url string:

```

await codio.course.exportStudentCSV(courseId, studentId)

```



Download exported student CSV data to filePath:

```

await codio.course.downloadStudentCSV(courseId, studentId, filePath)

```



#### Export assignment CSV



Returns url string:

```

await codio.course.exportAssignmentCSV(courseId, assignmentId)

```



Download exported assignment CSV data to filePath:

```

await codio.course.downloadAssignmentCSV(courseId, assignmentId, filePath)

```



#### Export LLM Proxy data



Returns url string:

```

await codio.course.exportLLMProxyData(courseId)

```



#### Export Coach data



Returns url string:

```

await codio.course.exportCoachData(courseId)

```



#### Export Assessment Data



Export all assessment results for selected assignments in the course.



The following data is exported to a .csv file for download

(or into a .zip file containing individual csv files if multiple assignments selected).



Returns archive url string:

```

await codio.course.exportAssessmentData(courseId, assignmentIds)

```



To download exported data you need to specify course Id : string, assignmentIds: string (comma-separated list of assignmentIds)

```

await codio.course.downloadAssessmentData(courseId, assignmentIds, filePath)

```

downloads file to filePath



#### Export Course Sources



Export all course sources.



Returns `CourseExport` object



```

CourseExport = {

  taskId: string

  done: boolean

  error?: string

  url?: string

}

```



```

await codio.course.createSourceExport(courseId)

```



To download exported data you need to specify course Id

```

await codio.course.downloadSourceExport(courseId, filePath)

```

downloads file to filePath



Get all available exports.



Returns array `CourseExport[]` objects



```

await codio.course.getSourceExports(courseId)

```



Get export progress by id.



Returns `CourseExport` object



```

await codio.course.getSourceExportProgress(courseId, taskId)

```



#### Export Course Work Data



Export all course work data.



Returns `CourseExport` object



```

CourseExport = {

  taskId: string

  done: boolean

  error?: string

  url?: string

}

```



```

await codio.course.createWorkExport(courseId)

```



To download exported data you need to specify course Id

```

await codio.course.downloadWorkExport(courseId, filePath)

```

downloads file to filePath



Get all available exports.



Returns array `CourseExport[]` objects



```

await codio.course.getWorkExports(courseId)

```



Get export progress by id.



Returns `CourseExport` object



```

await codio.course.getWorkExportProgress(courseId, taskId)

```



#### List organization courses



List organization courses



Returns



```

ListCoursesResponse = {

  courses: Course[],

  nextToken: string

}

```



Example



```

await codio.course.list(, )

```



#### Archive course



Returns `Date` of archivation



```

await codio.course.archive()

```



#### Filter Learners For Mentors



Specify mentors for LTI-base course



Returns



```

FilterLeanersResponce = {

  completed: boolean

}

```



Example



```

 = [{

  mentorId: string,

  learnerIds: string[]

}]

```



```

await codio.course.filterLearnersForMentors(, )

```



## Publish Stack

This method allow to publish the stack 

you need to specify 

`stackId : string` - stack to add new published version to,

`id: string | null` - stack id or stack version id to use as base,

`provisioner: string` - one of `ansible` or `bash` to detect which file to use `provision.sh` or `provision.yaml`,

`content: string | null` - content of `provision.yaml` or `provision.sh` file which overrides stored in archive if set (tar.gz is supported),

`archivePath: string | null` - path to archive with files to use during provision,

`message: string` - published version changelog



```javascript

  await codio.v1.stack.publish(

    stackId,

    id,

    provisioner,

    content,

    archivePath,

    message

  )



```



## Get Stack Info

`stackId : string` - stack id



```javascript

  await codio.v1.stack.info(stackId)

```



## Get Assignment Settings

`courseId : string` - course id,

`assignmentId : string` - assignment id,



Note: endTime field is Closing Date



returns `AssignmentSettings` - Settings, missed properties won't be updated

```javascript

  const settings = await codio.assignment.getSettings('', '')

```



```

  enableResetAssignmentByStudent?: boolean

  disableDownloadByStudent?: boolean

  visibilityOnDisabled?: string, // "READ_ONLY", "NO_ACCESS",

  visibilityOnCompleted?: string, // "READ_ONLY_RESUBMIT", "READ_ONLY", "NO_ACCESS",

  startTime?: Date | null,

  endTime?: Date | null,

  action?: string // "COMPLETE", "DISABLE", "DISABLE_AND_COMPLETE",

  dueTime?: Date | null

  markAsCompleteOnDueDate?: boolean

  penaltiesV2?: PenaltySettings

  examMode?: {

    timedExamMode: {

      enabled: boolean

      duration: number // minutes

    }

    shuffleQuestionsOrder: boolean

    forwardOnlyNavigation: boolean

    singleLogin: boolean

    authentication: boolean

  },

  releaseGrades?: boolean

  isDisabled?: boolean

}



export type PenaltySettings = {

  enable: boolean

  deductionIntervalMinutes: number

  deductionPercent: number

  lowestGradePercent: number

}

```



## Update Assignment Settings

This method allow updating assignment settings.

You need to specify

`courseId : string` - course id,

`assignmentId : string` - assignment id ,

`settings: AssignmentSettings` - Settings, missed properties won't be updated



Note: endTime field is Closing Date



Example: 

```javascript

  await codio.assignment.updateSettings('', '', {

    enableResetAssignmentByStudent: false,

    startTime: null,

    endTime: new Date('2022-05-10T23:59:59+01:00'),

    dueTime: new Date('2022-05-09T23:59:59+01:00'),

    penaltiesV2: {

      enable: true,

      deductionIntervalMinutes: 60,

      deductionPercent: 10,

      lowestGradePercent: 90

    }

  })

```



#### Update student related time extensions



Set time limits on a per-student basis



```javascript

 await codio.assignment.updateStudentTimeExtension(courseId, assignmentId, studentId, {

  extendedDeadline: minutes,

  extendedTimeLimit: minutes

})

```



returns empty object



## Get webhook events



### Load resent events



Get last events list with continuation token if more events are awailable



```

  await codio.v1.events.loadEvents('', )

```



return `LoadEventResponse` object

```

LoadEventResponse = {

  events: Event[],

  nextToken: string

}

Event = {

  id: string,

  event: any,

  completed: boolean,

  error?: string,

  issuedAt: Date

}

```



### Load all resent events



```

  await codio.v1.events.loadAllEvents()

```



return `Event` array



### Timezones:



We recommend using [Luxon](https://moment.github.io/luxon/) to deal with time zones.

```javascript

const { DateTime } = require('luxon')



DateTime.fromISO('2022-05-09T23:59:59').toJSDate() // to use local timezone

DateTime.fromISO('2022-05-09T23:59:59', { zone: 'EST' }).toJSDate() // to use other timezone

```