COSQOOL Partner API v1 · Overview

COSQOOL API Sandbox

Test your integration with the COSQOOL Partner API before you go live: browse the catalogue, enroll a test student, play a video, record progress and cancel access. Every action on these screens is a real call to the API you are connected to, and every answer can be read in full.

Sandbox videos use COSQOOL's demonstration clip instead of real lesson content. Different lessons may show the same clip. Each lesson keeps its own identifiers, access checks and progress records.

The API calls and their answers are real: you are testing your integration with demonstration media in place of the lesson recordings.

How testing works

Six stages, in this order. Each one opens the screen that runs it. The course, the student, the enrollment and the lesson item you pick are kept in this browser and reused by the next stage, so nothing has to be copied by hand.

  1. Stage 1: Connect

    Enter the sandbox API key COSQOOL issued to your organisation.

    The key is checked with a live request and then sent with every test call.

    Open Configuration
  2. Stage 2: Browse courses

    List or search the catalogue and open one course.

    The course answers its lessons, videos and quizzes, each with its own id.

    Browse courses
  3. Stage 3: Enroll a test student

    Generate a made-up student and enroll it in the course for a subscription term.

    The answer carries the enrollment id. Nobody is charged.

    Enroll a student
  4. Stage 4: Play video

    Request a lesson's video address through the normal delivery call and play it.

    The enrollment is checked on every request. The sandbox answers the demonstration clip.

    Play a video
  5. Stage 5: Record progress

    Report the completed video, or a quiz result, for that lesson item.

    The course progress is computed per student from the items you reported.

    Record progress
  6. Stage 6: Cancel access

    Cancel the enrollment, then ask for the video again.

    New video requests and progress writes are refused from that moment.

    Cancel access

Documentation

What this tool cannot test for you

  • Webhooks. Events are recorded for your key, and nothing is sent until COSQOOL holds your receiver's address, access token and signing secret. Until then, poll the change search.
  • Your own side. Signing your students in, selling the course and collecting payment happen on your platform. The API never charges anyone.
  • Production. It has its own base URL and its own key, and its video calls answer each lesson's own recording with a signed address that expires. A working sandbox test does not switch production on.

API reference

Complete documentation for the COSQOOL Partner API v1.0: enroll students, stream educational video content and track learning progress from your platform. The limit is 60 requests per minute per key.

Getting Started

Authentication

All requests must include an Authorization header with your Partner API key using the Api-Key scheme.

Request Header

Authorization: Api-Key sk_partner_<your key>

Security

Never expose your API key in client-side (frontend) code. All Partner API calls must be server-to-server: the key identifies your organisation, and whoever holds it can act as you.

Request conventions

Addresses. Every endpoint answers with and without the trailing slash (/enrollments and /enrollments/). Both forms are served directly, never through a redirect, so the method, the body, the key and the environment are the ones you sent.

Date-times. ISO 8601. expires_at must name its time zone: end the value with Z or with an offset such as +03:00(2027-01-31T21:00:00Z, 2027-02-01T00:00:00+03:00). A value without a zone, a date without a time, a number or an impossible date answers 400 validation_error with the field name. The read filter updated_since and the progress stamp completed_at read a value without a zone as UTC; a malformed value is 400 there as well. Date-times in API responses are UTC and end with Z.

The calls, in order
1

Discover Courses

Call GET /courses/{grade_slug}/{semester_slug}/ (or POST /courses/search) to find course IDs, then GET /courses/{course_id}/ for the flat course with an id on every item.

2

Enroll a Student

Call POST /enrollments/ with course_id, transaction_id and external_student_id (everything else is optional). Store the returned enrollment_id.

3

Stream Video Content

Call GET /students/{sid}/courses/{cid}/videos/{item_id}/ for one item's hls_url (or the v1 GET /enrollments/{id}/videos/ for every video). Each call re-checks the enrollment; `protection` says what protects the address it returns: `none` (the provider's common manifest address, which does not expire) or `signed_time_limited` (a token the provider refuses after `link_expires_at`). Request the address again rather than storing it. In the sandbox the same calls answer COSQOOL's demonstration clip for every eligible lesson (`video_delivery: demonstration`), unsigned; the lesson keeps its own ids and progress record.

4

Track Progress

Call POST /students/{sid}/courses/{cid}/progress/ per completed item and read GET …/progress/ — progress_pct (metric edumatch_item_completion_v1) is the authoritative course progress. The v1 …/complete/ counter and GET /students/{sid}/progress/ are legacy video counters.

Endpoints

GET/courses/{grade_slug}/{semester_slug}/

Returns all published courses for a given grade and semester. This is Step 1 of the integration workflow — use it to discover valid course_id values before enrolling students.

Course lists are cached until the next published content change on Cosqool servers (and never longer than 20 minutes): a published change, or a new course, shows in the next request.
NameInTypeRequiredDescription
grade_slugpathstringRequiredGrade identifier e.g. grade-10, grade-1 … grade-12
semester_slugpathstringRequiredSemester identifier: semester-1 or semester-2
subjectquerystringOptionalFilter by subject name (Arabic or English). Case-insensitive.

Example Response

{
  "grade_id": 10,
  "semester_id": 2,
  "count": 3,
  "courses": [
    {
      "course_id": 142,
      "title_en": "Physics — Grade 10 Term 2",
      "title_ar": "الفيزياء — الصف العاشر الفصل الثاني",
      "subject_id": 5,
      "subject_en": "Physics",
      "subject_ar": "فيزياء",
      "grade_id": 10,
      "semester_id": 2,
      "last_updated": "2025-09-01T08:00:00Z",
      "image_url": "https://www.cosqool.com/assets/course-covers/v1/grade-10-physics-semester-2.png"
    }
  ]
}

Course image. Every course in a list or detail answer carries image_url: the public HTTPS address of the course's cover, a PNG of 1920 × 1080 (16:9) that opens without a key, a login or a cookie, or null when the course has no cover. The same course has the same image_url in every answer (this list, the course detail and itscourse object, GET /courses/{course_id}/ and POST /courses/search). A published cover never changes at its address: a new design gets a new address. A new or changed cover does not move last_updated and sends no course.updated event, so read the image from the next list or detail answer.

Partner additions (catalogue search, flat course, per-item delivery, item progress, webhooks)

Additive endpoints on Partner API v1. Nothing above changes; every failure of these and of the original endpoints carries a stable code next to detail. Search, flat course and enrollment live on Catalog & Enrollment; delivery and progress on Video & Progress.

What the sandbox proves

The sandbox answers with the real Partner API contract, and it is tested as such: course structures and identifiers, prices and terms (with your sandbox key's sample prices), enrollment and cancellation, the delivery calls with their access checks and reason codes, progress, and webhooks once a receiver is connected follow the same rules and answer in the same form as in production.

One thing is replaced on purpose: the media. Every video address and every preview address the sandbox answers plays COSQOOL's demonstration clip — intentionally the same clip for every lesson — so playback, renewing an address (expires_at) and the whole integration flow are exercised without exposing lesson recordings. No lesson recording's address appears in any sandbox answer, whether as a manifest address, an iframe address, a thumbnail or any fallback field. The clip's address is public (protection: "none"), so a signed, expiring address (signed_time_limited) is seen in production only, where a production key receives each lesson's own recording.

A clip that repeats from lesson to lesson is therefore intended, not a defect. An unexpectedly empty course structure is one: a course is empty on purpose only in the case described under the flat course below ("A published course with no eligible content"); report any other empty course to COSQOOL.

Everything on this page is the shared Partner API contract. What is specific to one partner lives in that partner's key configuration on COSQOOL's side — the capabilities in the table below, its commercial terms, and its webhook receiver (see "outgoing events") — never in the request format.

What a key may do

Everything in this table is enabled per key by COSQOOL staff: the environment when the key is issued, every other capability only where staff enable it (none is on by default). None can be requested through the API; ask your COSQOOL contact. The last column is what a key without the capability meets.

CapabilityWhat it gives the keyWithout it
Environment (sandbox or production)Set when the key is issued. The key is served only by the host of its own environment, so a sandbox test never touches production data.The other environment's host refuses it before any data is touched: 403 environment_mismatch
Answer keys for native quizzescorrect on every question of a native quiz in the flat course, with answer_keys: included.The same questions without correct, with answer_keys: not_enabled_for_this_key. No error.
Test-preparation coursesThe Qudrat (90008) and Tahsili (90009) courses in search, the flat course, enrollment and the free previews.Those courses are not listed, and their ids answer like an unknown course: 404 course_not_found
Source content onlyA restriction: the key receives source content only — no lesson quiz generated by COSQOOL, and no lesson without a usable source video (its quizzes and files go with it). The sandbox applies it to every key.A production key without it also receives the lesson quizzes COSQOOL generated, and the quizzes and files of lessons without a usable source video. No error.
Free preview deliveryGET /courses/{course_id}/previews/ and …/previews/{video_id}/: the course's free preview videos, with no student and no enrollment.Both routes answer 403 preview_delivery_not_enabled
Bearer authorizationAuthorization: Bearer <key> is accepted besides Api-Key. Only the CoCreators reconciliation key carries it.A Bearer header is refused (send Api-Key): 401 bearer_not_allowed
Frame origins for iframe itemsThe https origins allowed to frame an item marked delivery: iframe (a dynamic activity; none exists today).The delivery of such an item answers 409 frame_origins_not_configured

Errors & Rate Limits

Error Schema

All errors return a consistent JSON object: a human-readable detail (a field map on validation errors) and a stable code — see the reason-code table above.

Error Response

{ "detail": "No active enrollment found for this student and course.", "code": "enrollment_not_found" }
HTTP Status Codes
CodeMeaningAction
200 OKRequest succeeded (or idempotent replay)Proceed normally
201 CreatedNew resource createdStore returned ID
400 Bad RequestInvalid or missing request parametersFix payload and retry
401 UnauthorizedMissing or malformed Authorization headerCheck your API key format
403 ForbiddenThe key may not do this, the key belongs to the other environment, or the enrollment is cancelled or expiredRead the code in the body (forbidden, environment_mismatch, enrollment_expired)
404 Not FoundResource doesn't exist (intentionally vague for security)Verify course/enrollment IDs
429 Too Many RequestsRate limit exceeded (60 requests per minute per key)Wait for Retry-After header duration
409 ConflictThe request is valid but cannot be carried out as it stands (see the reason codes)Read the code in the body
500 Server ErrorUnexpected server-side failureRetry with exponential backoff; contact support if persistent
503 UnavailableA video address cannot be issued right now (video_signing_unavailable, video_delivery_suspended)Try again later; nothing else is affected
Rate Limits & Retry Strategy

60

requests per minute per key

429

with Retry-After when exceeded — no daily cap

When the limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating the number of seconds to wait. Implement exponential backoff with a maximum of 3 retries for 429 and 500 errors.

Ready to start testing?

Run the six stages against the environment you are connected to, starting with the catalogue.