Importing Content

This API allows authorized content partners to import learning content metadata into the Skillsoft Platform, making it accessible and discoverable to learners via the platform’s content catalog. It is designed to support bulk ingestion and automated synchronization of external content catalogs.

Overview

The Content Import API is used to:

  • Integrate external course catalogs into the Skillsoft Platform.
  • Automate the bulk upload of learning content.
  • Ensure content is structured, searchable, and properly categorized.

When to Use

Use this API when:

  • A federated content partner wants to onboard content into the Skillsoft Platform.
  • There is a need to automate ingestion of third-party learning assets.
  • Metadata updates or bulk content mapping is required.

Supported Use Cases

Scenario Description
Bulk Content Onboarding A content partner sends 500+ training assets in a nightly job using the API.
Metadata-Only Push For externally hosted content, only metadata is imported, not the file itself.
Content Enrichment Periodic updates to fields like title, tags, and thumbnail are made through re-posting.
Federated Hosting Sync Content is hosted on the provider’s site, but the Skillsoft Platform surfaces it with accurate metadata.

API Description

Endpoint

http

POST /v1/partners/{partnerName}/organizations/{orgId}/content

Important: See https://api.percipio.com/content-aggregation/api-docs/ for detailed API information.

Request Body and JSON Schema

The request must include a valid JSON payload with the following structure:

json

 

{

"content_id": "ext-course-001",

"title": "Foundations of Cloud Security",

"type": "VIDEO",

"duration": 900,

"language": "en",

"url": "https://yourdomain.com/cloud-security-intro",

"description": "An introduction to cloud security fundamentals.",

"tags": ["cloud", "security", "cyber"],

"thumbnail_url": "https://yourdomain.com/thumbnails/cloud-sec-thumb.jpg",

"author": "YourOrg Academy"

}

Field-Level Examples and Validation

Field Mandatory Format Example Validation Rules
content_id Yes string "ext-course-001" Unique per partner; maximum 100 characters
title Yes string "Effective Communication" Maximum 255 characters
type Yes enum (VIDEO, SCORM, DOC, etc.) "SCORM" Only accepted values are allowed
duration No integer (seconds) 1200 Positive integer only
language No ISO 639-1 code "en" Two-letter lowercase (e.g., "fr", "de")
url Yes valid HTTPS URL "https://provider.com/course-123" Must be accessible and start with https://
description No string "This course covers the basics of Agile." Maximum 2000 characters
tags No array of strings ["agile", "scrum"] Maximum 10 tags & 30 characters each
thumbnail_url No valid HTTPS URL "https://provider.com/thumbnails/img123.jpg" Optional image display
author No string "ABC Learning Co." Free text, maximum 100 characters

Sample Payloads

Minimum Required Example:

json

 

{

"content_id": "int-course-001",

"title": "Time Management Essentials",

"type": "VIDEO",

"url": "https://yourorg.com/time-management"

}

Full Metadata Example:

json

 

{

"content_id": "ext-course-202",

"title": "Inclusive Leadership Workshop",

"type": "SCORM",

"duration": 1800,

"language": "en",

"description": "Learn strategies for inclusive leadership in diverse teams.",

"url": "https://yourdomain.com/inclusive-leadership",

"tags": ["leadership", "diversity", "team"],

"author": "Global HR Group",

"thumbnail_url": "https://yourdomain.com/thumbs/inclusive.jpg"

}

Integration Scenario: End-to-End Example

Scenario: A federated content provider uses an automated nightly process to push 200 new courses into the Skillsoft Platform using the API.

  1. At 2:00 AM UTC, a scheduled job generates a JSON file of all new or updated courses.
  2. A secure OAuth2 token is retrieved using the Client ID/Secret.
  3. A POST request is made to the import endpoint with the JSON payload.
  4. If successful, a 201 Created response is received.
  5. If failures occur, the script captures and logs them for retry or investigation.

This procedure enables near real-time catalog syncing between the platform and the partner LMS.

Authentication Requirements

This API requires OAuth2 token-based authentication using the Client Credentials Grant Flow.

  • Token Endpoint:

    https://oauth2-provider.develop.squads-dev.com/oauth2-provider/token

  • Sample cURL:

    bash

     

    curl -X POST "https://oauth2-provider.develop.squads-dev.com/oauth2-provider/token" \

    -H "Content-Type: application/json" \

    -d '{

    "client_id": "<your-client-id>",

    "client_secret": "<your-client-secret>",

    "grant_type": "client_credentials",

    "scope": "api"

    }'

Where to get the Client ID/Secret?

Client credentials are issued during Skillsoft Platform on-boarding. If you have not completed the on-boarding process yet, please contact your Skillsoft Account Representative or Integration Manager.

For detailed on-boarding steps, see "Skillsoft On-boarding Guide".

Environment

Ensure that you use the appropriate base URL and credentials for the Skillsoft Platform environment. Using incorrect details will result in errors.

Rate Limits and Throttling

The Skillsoft Platform enforces rate limits and payload size thresholds to ensure consistent platform performance and fair usage across all integration partners. When integrating your LMS or content platform with the Skillsoft Platform using inbound APIs (e.g., Content Import, Track, or Statements), it is essential to understand and design around these limits.

Limit Type Value Why It Matters
Max requests per minute 60 Prevents high-frequency automated sync jobs from overwhelming the API back-end
Max payload size 2 MB Ensures stable ingestion and avoids timeouts due to excessively large requests
Retry-After (on 429) ~30 seconds Instructs clients how long to wait before retrying after hitting the rate limit

We recommend that you implement an exponential back-off strategy when retrying failed requests. Avoid constant polling or retrying too soon, which can lead to cascading failures.

Real-World LMS Use Case Examples

  • Track API – Bulk Completion Sync : A partner LMS sends thousands of learner completion records.

    ✅ Solution: Split records into batches that respect the 60 requests per /minute and 2 MB payload cap.

  • Content Import – Course Catalog Push: A provider pushes metadata for 500 new courses.

    ✅ Solution: Chunk the request data into smaller payloads to stay under the 2 MB limit.

  • xAPI Statements – Activity Logging: An xAPI-compliant platform pushes real-time events like "started", "completed", and "passed". If the platform sends bursts of events too quickly, it may trigger a “429” error.

    ✅ Solution: Detect the 429 Too Many Requests response and pause based on Retry-After.

Summary

  • Rate limits are not negotiable — you must architect your integration to comply.
  • Implement batching, payload compression, and throttled retries for smooth operation.
  • Monitor for 429 responses and use Retry-After headers to avoid being blocked.
  • Build your sync jobs to scale gracefully, not aggressively.

By respecting these constraints, you will ensure a stable, predictable, and accurately performing integration with the Skillsoft Platform.

Response Handling

  1. Success (201 Created):

    json

     

    {

    "status": "SUCCESS",

    "message": "Content successfully imported."

    }

  2. Failure (400 / 401 / 500):

    3. json

     

    {

    "status": "ERROR",

    "message": "Missing required field: title"

    }

    Error Codes

    Code Description Resolution
    400 Bad Request Check required fields and schema
    401 Not Authorized / Authorized Verify token and client credentials
    409 Conflict Duplicate content_id already exists
    500 Internal Server Error Contact support or retry after some time

Best Practices for Using the Content Import API

  • Ensure that you use your consistent and unique content_id value.
  • Test your payloads in the Development environment before moving to Production.
  • Include metadata such as tags, description, and thumbnail_url to improve content discoverability.
  • Use versioning in your internal content to manage updates efficiently.
  • Validate your content catalog regularly and frequently to ensure all entries appear correctly in the platform.