Syllabus skills extraction

Extract structured, normalized skills from syllabus PDFs using the Mapademics Embedded API.

Extract structured, normalized skills from syllabus PDFs.

The Syllabus Skills Extraction capability analyzes academic syllabi to identify the skills students are expected to develop. It ingests syllabus PDFs, applies Mapademics' skills intelligence, and returns machine-readable skill data suitable for curriculum analysis, reporting, and product embedding.

---

What this enables

Use syllabus skills extraction to:

• Convert syllabus documents into structured skill data

• Normalize skills to stable identifiers for cross-course comparison

• Assign proficiency levels to each skill

• Surface evidence explaining why a skill was identified

This capability is designed for curriculum-focused workflows, not free-form text analysis.

---

Typical use cases

• Curriculum development — Identify strengths, gaps, and overlaps across courses or programs

• Program review & assessment — Support accreditation and outcomes reporting

• Skills dashboards — Power course- and program-level skills views

• Student transparency — Show students what skills a course develops

• Career alignment — Map curriculum to downstream workforce needs

---

How it works

Syllabus skills extraction follows a three-step flow:

1. Upload — Submit a syllabus PDF

2. Process — Skills are extracted and normalized asynchronously

3. Retrieve — Structured skill results are returned

Treat extraction as an asynchronous job. Your product should reflect processing state and fetch results when ready.

---

Authentication

All requests require:

• Platform API key

• Customer API key (required for most production requests)

See Authentication.

---

Inputs

Supported input

• Syllabus PDF (required)

PDF is the only supported input format.

Recommended characteristics

• Text-based PDFs (not scanned images)

• Clear learning objectives, outcomes, topics, or assessments

• Standard academic syllabus structure

Scanned or image-only PDFs should be OCR'd upstream. Without OCR, extraction quality will be significantly reduced.

---

Integration walkthrough

This section describes the canonical integration pattern. It mirrors the API's lifecycle and is intended to be implemented end-to-end.

---

Step 1 — Upload a syllabus

Upload a syllabus PDF to initiate skill extraction.

curl -X POST https://embedded-api.mapademics.com/v1/skills-extraction/syllabus \
  -H "Authorization: Bearer $MAPADEMICS_API_KEY" \
  -H "X-Customer-Key: $MAPADEMICS_CUSTOMER_KEY" \
  -F "[email protected]"

You can attach optional metadata that overrides any AI-extracted values:

curl -X POST https://embedded-api.mapademics.com/v1/skills-extraction/syllabus \
  -H "Authorization: Bearer $MAPADEMICS_API_KEY" \
  -H "X-Customer-Key: $MAPADEMICS_CUSTOMER_KEY" \
  -F "[email protected]" \
  -F 'metadata={"title":"Introduction to Data Science","courseCode":"CS 101","instructor":"Dr. Smith"}'

Supported metadata fields: title, courseCode, instructor, description, sectionName, sectionDescription. These values take precedence over any metadata the AI extracts from the document.

What to persist:

• The extractionId returned by the API

• The course, term, or program context associated with the upload

This identifier is the durable reference for retrieving results.

---

Step 2 — Handle processing state

Extraction typically completes within 30–90 seconds.

Recommended patterns:

• Show a "Processing syllabus…" state in your UI

• Poll the task status endpoint at a reasonable interval (e.g., every 2–5 seconds)

• Allow users to refresh or revisit results later

---

Step 3 — Retrieve extracted skills

Retrieve results using the extractionId from Step 1.

curl https://embedded-api.mapademics.com/v1/skills-extraction/syllabus/{extractionId} \
  -H "Authorization: Bearer $MAPADEMICS_API_KEY" \
  -H "X-Customer-Key: $MAPADEMICS_CUSTOMER_KEY"

Replace {extractionId} with the identifier returned during upload.

---

What you get back

Each extraction returns a list of skills with proficiency levels and supporting context.

Skill object

{
  skillId: string;
  level: number;
  mode: "explicit" | "implicit";
  rationale?: string;
}

Field definitions

Field	Description
skillId	Stable identifier from the Mapademics Skills Library
level	Proficiency level (1–5)
mode	Whether the skill was explicitly stated or implicitly inferred
rationale	Optional explanation supporting the skill assignment

---

Proficiency levels

Skill levels are returned as a numeric value with the following semantics:

Level	Name	Meaning
1	Foundational	Basic awareness or introduction
2	Developing	Building competency through practice
3	Proficient	Consistent application in standard contexts
4	Advanced	Application in complex or novel situations
5	Expert	Mastery and ability to teach others

Levels are a core product signal and are intended to be used directly in downstream logic and UI.

Examples:

• Comparing depth across courses

• Rolling up program-level skill maturity

• Highlighting advanced or expert-level coverage

• Supporting accreditation and outcomes frameworks

---

Example response (truncated)

{
  "object": "syllabus_extraction",
  "data": {
    "extractionId": "syl_abc123xyz",
    "metadata": {
      "courseName": "Introduction to Data Science",
      "courseCode": "CS 101",
      "courseDescription": "An introductory course covering data analysis fundamentals.",
      "sectionName": "Section A",
      "sectionDescription": "Monday/Wednesday section",
      "instructor": "Dr. Smith"
    },
    "skills": [
      {
        "skillId": "msl_skill_0089",
        "level": 3,
        "mode": "implicit",
        "rationale": "Course outcomes emphasize applying statistical methods to real datasets."
      },
      {
        "skillId": "msl_skill_0127",
        "level": 4,
        "mode": "explicit",
        "rationale": "Advanced programming techniques are explicitly listed in weekly topics."
      }
    ]
  }
}

---

Using the results effectively

Recommended practices:

• Treat skillId as the canonical reference for storage and comparison

• Use level as a first-class signal in analytics and UI

• Use mode and rationale to build transparency and trust

• Expect results to improve as syllabus quality and structure improve

---

Common issues

Issue	Cause	Resolution
401 Unauthorized	Invalid or missing platform API key	Verify the Authorization header
403 Forbidden	Missing or invalid customer API key	Confirm the X-Customer-Key header
Sparse results	Syllabus lacks explicit learning outcomes or structured content	Improve syllabus structure or set expectations
Unexpected levels	Syllabus language is broad or non-specific	Review source document quality

For detailed error behavior, see Error Handling.

---

Next steps

• Integration Guide — Step-by-step implementation details

• API Reference — Full endpoint documentation

• Core Concepts — Understanding skills and proficiency levels

• The Mapademics Skills Library — Browse the skills taxonomy