Upload a media

POST /api/v1/media

Uploads an image or a document into the school's media library. The body is multipart/form-data with one part named file. A video is refused here: it goes to the video host through Upload a lesson video.

Authorization

Request headers

No Idempotency-Key: an upload claims no key, and every call stores a new file. There is no replay.

Request body

Example

curl -X POST "$COHORTE_API_BASE_URL/api/v1/media" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -F "file=@./syllabus.pdf"

Response

• 201 Created — the media, ready.
• 400 Bad Request — no file part, an empty file, a video, a type not listed above, a file over 3 MB, or a refused file name.
• 401 Unauthorized — missing, unknown or expired key.
• 403 Forbidden — the bearer is not OWNER or ADMIN.

Response fields

Same fields as one item of List media; usage is empty.

Example response

{
  "success": true,
  "data": {
    "id": "9d0e1f2a-3b4c-4d5e-8f6a-7b8c9d0e1f2a",
    "kind": "document",
    "provider": "storage",
    "source": "upload",
    "url": "https://files.example.com/organizations/…/document-1759300000000.pdf",
    "title": "syllabus.pdf",
    "status": "ready",
    "progress": null,
    "durationSeconds": null,
    "mimeType": "application/pdf",
    "sizeBytes": 248312,
    "createdAt": "2026-10-01T08:30:00.000Z",
    "archived": false,
    "usage": []
  },
  "correlationId": "c0ffee00-1111-4222-8333-444455556666"
}

Notes

• Attach the returned id to a lesson with Attach a resource (type: file, mediaId).

Related

• List media
• Rename a media
• Upload a lesson resource