Files and uploads

Three steps

1. POST /v1/files with the file name, type and exact size. The response has the file’s id, an upload_url, the upload_headers to send and upload_expires_at.
2. PUT the bytes to upload_url with every header in upload_headers, before upload_expires_at (about an hour). When upload_url is the API’s own /v1/files/{id}/content, also send your Authorization header; never send it to any other upload URL.
3. POST /v1/files/{id}/complete. EduMark checks the type and contents and scans for malware. When status is scanning, call again after a few seconds; use the file once it is ready.

# 1. Create the file. Keep `id` (FILE_ID), `upload_url` (UPLOAD_URL) and `upload_headers`.
curl -X POST https://api.edumark.ai/v1/files \
  -H "Authorization: Bearer $EDUMARK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"filename": "essay.docx", "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "size_bytes": 48211}'

# 2. Upload the bytes with the upload_headers (here, its Content-Type).
#    Add -H "Authorization: Bearer $EDUMARK_API_KEY" only when UPLOAD_URL is https://api.edumark.ai/v1/files/$FILE_ID/content.
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document" \
  --data-binary @essay.docx

# 3. Finish the upload.
curl -X POST https://api.edumark.ai/v1/files/$FILE_ID/complete \
  -H "Authorization: Bearer $EDUMARK_API_KEY"

Then send {"file_id": "file_…"} (the id from step 1) in any field that takes a document, such as document in marking or file in transcriptions and course imports. The file’s own expires_at is when EduMark deletes it: 30 days after upload, or sooner if you delete it.

Limits

Files over 20 MiB use the presigned upload URL that POST /v1/files returns. Recordings and course files are checked on a worker, so complete usually answers scanning: check again with GET /v1/files/{id} until the file is ready.

Fields that take a document also accept the older inline form {"filename", "base64", "mime_type"}. It is handy for tests, but uploads are faster and more reliable for anything larger than a few megabytes.

Course files

A course file is a course exported from another platform: a Moodle backup (.mbz), an IMS Common Cartridge or Canvas export (.imscc or .zip), a Blackboard export, a SCORM 1.2 or 2004, IMS content package, xAPI, cmi5 or H5P zip, or a GIFT, Aiken, QTI or Moodle XML question file. Send application/zip for zips and .imscc files, application/vnd.moodle.backup for .mbz and text/plain for .gift.

EduMark checks a course file the way its own course library does. It must be what its name says, not password protected, and a course export EduMark can read. A file that fails is rejected, and its error says what to do: SOURCE_ARCHIVE_ENCRYPTED (export it again without a password), SOURCE_ARCHIVE_UNSAFE (it unpacks too far: split it) or SOURCE_PACKAGE_UNRECOGNISED (not a course export). Then send it to course imports.