iblai-api-catalog-media

Manage an organization's catalog media resources from the API: media files and external links (videos, images, documents, audio, other) attached to a course, a unit, a specific resource item, or any combination of the three. Supports listing/filtering, full CRUD, a search action, and a by-item lookup. The itemtype (which catalog level the media is associated with) is derived automatically from which of courseid / unitid / itemid you supply. Use when attaching media to catalog content, browsing/searching an org's media, or uploading media files.

Auth & conventions

• Base URL: https://api.iblai.app/dm — these are Data Manager (DM)

endpoints, so the /dm prefix is required; the /api/media/orgs/{org}/users/{user_id}/media/media-resources/... paths below are appended to it (e.g. https://api.iblai.app/dm/api/media/orgs/enterprise/users/36/media/media-resources/).

• Header: Authorization: Api-Token $IBLAIAPIKEY on every request.
• Path vars: {org} = $IBLAI_ORG (the org key — matched against the

platform's org), {user_id} = the numeric user id (matched against User.id; this is not the username). Both org and user are baked into the path here (unlike most catalog endpoints, which pass them as params).

• Auth classes: session, OAuth2 client-credential, and platform Api-Token.
• DELETE / destructive / outward-facing calls (delete, file upload) say

"Confirm with the user first."

• Not connected yet? Run /iblai-api-login first to populate IBLAI_ORG,

IBLAIUSERNAME, and IBLAIAPIKEY. (userid is the numeric id, not the username IBLAI_USERNAME.)

All routes are under /api/media/orgs/{org}/users/{user_id}/media/media-resources/.

Reads

Media resources (CRUD)

• GET …/media-resources/ — list media resources for the org's platform

(paginated, newest-first). Filters (query params, mutually exclusive in this precedence): search (icontains across title, description, courseid, unitid, itemid, fileurl), else courseid + unitid, else courseid, else unitid, else itemid. The id filters also pull in rows whose itemtype spans that level (e.g. filtering by courseid also returns course, courseunit, course_resource, and all items).

• GET …/media-resources/{id}/ — retrieve one media resource by numeric id.

Search

• GET …/media-resources/search/ — paginated search action. **q

required** (icontains across title, description, courseid, unitid, itemid, fileurl). Optional result filters courseid, unitid, itemid (same itemtype-spanning behavior as the list endpoint, applied before the q match). Returns the standard paginated envelope.

By-item

• GET …/media-resources/by_item/ — fetch media for one catalog item.

itemtype and itemid both required (missing → 400). itemtype values: course, unit, resource, courseunit, courseresource, unitresource, all. For course/unit/resource, the lookup matches the corresponding id (courseid/unitid/itemid = itemid) or any itemtype that spans that level; for the combined types it matches itemtype + item_id exactly. Returns the standard paginated envelope.

Writes

Media resources (CRUD)

• POST …/media-resources/ — create a media resource. Admin only.

Accepts JSON or multipart/form-data (for the file upload). At least one of courseid / unitid / itemid is required; itemtype is computed server-side and is read-only. Confirm with the user first (file upload / write): ``json { "title": "string (required)", "mediatype": "video|image|document|audio|other (required)", "description": "string", "file": "binary file (multipart only)", "fileurl": "https://… (external URL)", "courseid": "course-v1:ORG+NUM+RUN", "unitid": "block-v1:ORG+NUM+RUN+type@vertical+block@…", "itemid": "string" } ` Provide either file (upload) or fileurl (external link). Creating a second resource with the same file/fileurl for the same itemtype + itemid is rejected as a duplicate (400). createdby is set to the path {user_id}; platform is set from {org}`.

• PUT …/media-resources/{id}/ — full update. Admin only. Same body

fields as create (multipart supported). Same duplicate-file/fileurl guard. itemtype/platform/created_by stay read-only. Confirm with the user first.

• PATCH …/media-resources/{id}/ — partial update (same rules as PUT).

Confirm with the user first.

• DELETE …/media-resources/{id}/ — delete a media resource by id. Confirm

with the user first.

Example

List the first page of an org's media resources filtered to one course (note the URL-encoded course_id):

curl -G \
  "https://api.iblai.app/dm/api/media/orgs/$IBLAI_ORG/users/36/media/media-resources/" \
  -H "Authorization: Api-Token $IBLAI_API_KEY" \
  --data-urlencode "course_id=course-v1:main+NB101+2025-T1" \
  --data-urlencode "page_size=10"

Search across an org's media for "lecture":

curl -G \
  "https://api.iblai.app/dm/api/media/orgs/$IBLAI_ORG/users/36/media/media-resources/search/" \
  -H "Authorization: Api-Token $IBLAI_API_KEY" \
  --data-urlencode "q=lecture"

Notes

• item_type values (the catalog level a media resource is associated with):

course, unit, resource, courseunit, courseresource, unitresource, all. It is never sent by the client — the server computes it from which of courseid / unitid / itemid are present (course+unit+item → all; course+unit → courseunit; course+item → courseresource; unit+item → unit_resource; a single id → that single type). It is exposed read-only in responses.

• media_type values: video, image, document, audio, other.
• File upload. Send file as multipart/form-data (binary), or instead

give an external file_url. Uploading the same file/URL for the same item is rejected as a duplicate. Treat uploads as outward-facing — confirm with the user first.

• Pagination envelope (custom; not the catalog {count,next_page,…}

shape). List/search/by-item return: ``json { "status": { "success": true, "description": "Successfully retrieved media resources" }, "results": { "count": 1, "next": null, "previous": null, "data": [ … ] } } ` Page size is page_size (default 10, max 100); page via page`. Detail, create, and update responses return the bare serialized object instead.

• Resource fields in data[]: id, title, description, media_type,

itemtype, courseid, unitid, itemid, platform, fileurl, file, createdby, createdat, updatedat. createdby, createdat, updatedat, itemtype, and platform are read-only.

• Permissions (MediaResourcePermission): the path {user_id} must have an

active UserPlatformLink to the {org} platform. Reads (safe methods) need only that active link; writes (POST/PUT/PATCH/DELETE) additionally require that link to be admin (is_admin). A missing user, unknown org, or no active link all fail the check. Object-level access also requires the resource's platform.org to equal the path {org}.

• Org / user resolution. {org} is matched against Platform.org and

{user_id} against User.id; an unknown org yields an empty result set (or permission failure on writes). Unlike the rest of /iblai-api-catalog, org and user are path segments, not query/body params.