article Example

This example demonstrates creating article-style content optimized for reading and reference.

Basic Article Example

Create a simple article:

curl -X POST "https://{your-instance-url}/incoming/v2/content/course/create" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -d '{
    "courseAttributes": [
      {
        "title": "Getting Started with GraphQL",
        "kind": "article",
        "availableToPublic": true,
        "articleVariant": {
          "language": "en",
          "label": "English",
          "title": "Getting Started with GraphQL",
          "subtitle": "A comprehensive guide to using GraphQL in your applications",
          "body": "<h1>Introduction to GraphQL</h1><p>GraphQL is a query language for APIs...</p><h2>Key Benefits</h2><ul><li>Flexible queries</li><li>Strong typing</li><li>Single endpoint</li></ul>"
        }
      }
    ]
  }'

Response Example

["article-def456"]

Long-Form Article

Create a comprehensive article with rich formatting:

{
  "courseAttributes": [
    {
      "title": "The Complete Guide to API Design",
      "kind": "article",
      "sku": "GUIDE-API-001",
      "availableToPublic": true,
      "articleVariant": {
        "language": "en",
        "label": "English",
        "title": "The Complete Guide to API Design",
        "subtitle": "Best Practices and Patterns",
        "body": "<h1>API Design Fundamentals</h1><p>Good API design is crucial for developer experience...</p><h2>RESTful Principles</h2><p>REST APIs follow these core principles:</p><ul><li>Stateless communication</li><li>Resource-based URLs</li><li>Standard HTTP methods</li></ul><h2>Authentication</h2><p>Secure your APIs with proper authentication:</p><pre><code>Authorization: Bearer YOUR_TOKEN</code></pre><h2>Versioning Strategies</h2><p>Plan for API evolution from day one...</p><h2>Documentation</h2><p>Clear documentation is essential for API adoption...</p>",
        "copyright": "© 2024 Your Company. All rights reserved."
      }
    }
  ]
}

Knowledge Base Article

Create articles for your knowledge base:

{
  "courseAttributes": [
    {
      "title": "How to Reset Your Password",
      "kind": "article",
      "availableToPublic": true,
      "articleVariant": {
        "language": "en",
        "label": "English",
        "title": "How to Reset Your Password",
        "subtitle": "Step-by-step instructions",
        "body": "<h1>Password Reset Guide</h1><p>If you've forgotten your password, follow these steps:</p><ol><li>Go to the login page</li><li>Click 'Forgot Password'</li><li>Enter your email address</li><li>Check your email for reset link</li><li>Click the link and create a new password</li></ol><h2>Password Requirements</h2><ul><li>Minimum 8 characters</li><li>At least one uppercase letter</li><li>At least one number</li><li>At least one special character</li></ul><h2>Need More Help?</h2><p>Contact support at [email protected]</p>"
      }
    }
  ]
}

Technical Documentation Article

Create technical documentation:

{
  "courseAttributes": [
    {
      "title": "API Rate Limiting Implementation",
      "kind": "article",
      "availableToPublic": false,
      "articleVariant": {
        "language": "en",
        "label": "English",
        "title": "API Rate Limiting Implementation",
        "subtitle": "Technical Reference",
        "body": "<h1>Rate Limiting Overview</h1><p>Our API implements rate limiting to ensure fair usage...</p><h2>Rate Limit Headers</h2><table><thead><tr><th>Header</th><th>Description</th></tr></thead><tbody><tr><td>X-RateLimit-Limit</td><td>Maximum requests allowed</td></tr><tr><td>X-RateLimit-Remaining</td><td>Requests remaining</td></tr></tbody></table><h2>Implementation Details</h2><pre><code class='language-javascript'>const rateLimit = require('express-rate-limit');\n\nconst limiter = rateLimit({\n  windowMs: 60000,\n  max: 100\n});</code></pre><h2>Handling Rate Limits</h2><p>When you receive a 429 response, wait for the time specified in the Retry-After header...</p>",
        "copyright": "© 2024 Engineering Team"
      }
    }
  ]
}

Article with External Link

Link to external resources:

{
  "courseAttributes": [
    {
      "title": "Product Documentation",
      "kind": "article",
      "availableToPublic": true,
      "articleVariant": {
        "language": "en",
        "label": "English",
        "title": "Product Documentation",
        "subtitle": "Complete product reference",
        "body": "<h1>Documentation Overview</h1><p>For the most up-to-date documentation, visit our external docs site.</p>",
        "externalUrl": "https://docs.example.com/product",
        "externalUrlCallToAction": "Visit Full Documentation"
      }
    }
  ]
}

Multilingual Article

Create an article with multiple language variants:

To create multilingual content, create separate articles for each language and link them through tags or custom fields, or use the topics structure within a courseGroup.

Note: The articleVariant object itself is for a single language. To support multiple languages, you would create separate article courses or use a courseGroup with article-type topics.

Article with Code Examples

Include syntax-highlighted code:

{
  "courseAttributes": [
    {
      "title": "JavaScript Array Methods Cheat Sheet",
      "kind": "article",
      "availableToPublic": true,
      "articleVariant": {
        "language": "en",
        "label": "English",
        "title": "JavaScript Array Methods Cheat Sheet",
        "subtitle": "Quick reference for common array methods",
        "body": "<h1>Array Methods</h1><h2>map()</h2><p>Transform each element:</p><pre><code class='language-javascript'>const numbers = [1, 2, 3];\nconst doubled = numbers.map(n => n * 2);\n// [2, 4, 6]</code></pre><h2>filter()</h2><p>Select elements by condition:</p><pre><code class='language-javascript'>const numbers = [1, 2, 3, 4];\nconst evens = numbers.filter(n => n % 2 === 0);\n// [2, 4]</code></pre><h2>reduce()</h2><p>Combine elements:</p><pre><code class='language-javascript'>const numbers = [1, 2, 3];\nconst sum = numbers.reduce((a, b) => a + b, 0);\n// 6</code></pre>"
      }
    }
  ]
}

Use Cases

Documentation

Perfect for:

• API documentation
• User guides
• Technical references
• FAQs

Knowledge Base

Ideal for:

• How-to articles
• Troubleshooting guides
• Product documentation
• Support articles

Blog Posts

Great for:

• Industry insights
• Best practices
• Case studies
• Tutorials

Quick Reference

Excellent for:

• Cheat sheets
• Quick starts
• Configuration guides
• Command references

Best Practices

1. Structure Content Well

<h1>Main Title</h1>
<p>Introduction paragraph...</p>

<h2>Section 1</h2>
<p>Section content...</p>
<ul>
  <li>Point 1</li>
  <li>Point 2</li>
</ul>

<h2>Section 2</h2>
<p>More content...</p>

Use semantic HTML for better readability and SEO.

2. Use Descriptive Titles

Good titles:

• ✅ "How to Reset Your Password"
• ✅ "Getting Started with GraphQL"
• ✅ "API Rate Limiting Guide"

Poor titles:

• ❌ "Tutorial"
• ❌ "Guide 1"
• ❌ "Documentation"

3. Include Subtitles

Subtitles provide context and improve discoverability:

{
  "title": "API Design Guide",
  "subtitle": "Best practices for building RESTful APIs"
}

4. Use Rich Formatting

Supported HTML elements:

<!-- Headings -->
<h1>, <h2>, <h3>, <h4>, <h5>, <h6>

<!-- Text formatting -->
<p>, <strong>, <em>, <u>, <span>, <div>

<!-- Lists -->
<ul>, <ol>, <li>

<!-- Links and media -->
<a href="">, <img src="" alt="">

<!-- Tables -->
<table>, <thead>, <tbody>, <tr>, <th>, <td>

<!-- Code -->
<pre>, <code>

<!-- Other -->
<blockquote>, <hr>

5. Code Block Syntax Highlighting

Use class attribute for syntax highlighting:

<pre><code class="language-javascript">
const example = "code here";
</code></pre>

Supported languages:

• language-javascript
• language-python
• language-java
• language-bash
• language-json
• language-html
• language-css

6. Use Copyright Notices

Protect your content:

{
  "copyright": "© 2024 Your Company. All rights reserved."
}

HTML Content Guidelines

Character Limits

• title: 255 characters
• subtitle: 500 characters
• body: No strict limit, but keep reasonable for performance

Best Practices

• Use semantic HTML5 elements
• Include alt text for images
• Use proper heading hierarchy (h1 → h2 → h3)
• Keep paragraphs concise
• Use lists for multiple related items
• Include code examples in <pre><code> blocks

Common Errors

Missing articleVariant

{
  "error": "Article kind requires articleVariant object"
}

Solution: Include the articleVariant object with all required fields.

Invalid HTML

{
  "error": "Article body contains invalid HTML"
}

Solution: Validate HTML structure - ensure all tags are properly closed.

Missing Required Fields

{
  "error": "articleVariant requires language, label, title, and body"
}

Solution: Include all required fields in the articleVariant object.

Next Steps

• Review other format examples:
  • courseGroup Example
  • video Example
  • shareableContentObject (SCORM) Example
  • microCourse Example
• Explore Field Reference