Knowledge Base API Quickstart Guide

Knowledge Base API Documentation

The Knowledge Base API provides endpoints for managing articles, categories, and content in your knowledge base system. This API supports importing, updating, deleting, and retrieving articles with full multilingual support.

Base URL

https://api.productfruits.com/v1/knowledgebase

Authentication

All API requests require authentication using your API key as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Authorization: Please see the guide on obtaining and managing API keys.

Knowledge Base API Endpoints

Quick Start Example

Here's a simple example of importing an article:

Request: POST /knowledge-base/v1/import

{
  "articles": [
    {
      "correlationId": "getting-started-001",
      "categoryCorrelationId": "tutorials",
      "isPrivate": false,
      "contents": [
        {
          "lang": "en",
          "title": "Getting Started Guide",
          "content": "# Welcome\n\nThis guide will help you get started...",
          "format": "markdown",
          "publishStatus": "published"
        }
      ]
    }
  ]
}

Response: 200 OK

{
  "errors": [],
  "results": [
    {
      "correlationId": "getting-started-001",
      "articleId": 123,
      "status": "created",
      "contents": [
        {
          "lang": "en",
          "contentId": 456,
          "slug": "getting-started-guide",
          "status": "created",
          "published": true
        }
      ],
      "errors": []
    }
  ]
}

Key Concepts

Correlation IDs

Correlation IDs allow you to sync your external system IDs with our internal database IDs. We store your correlation IDs and use them to find and match entities for updates.

• Article Correlation ID: Your external identifier for articles (e.g., from your CMS, database, or system)
• Content Correlation ID: Your external identifier for content versions within articles
• Category Correlation ID: Your external identifier for categories used in article organization

ID Format Options:

• Your External IDs: Use any string identifier from your system (e.g., "cms-article-123", "help-guide-v2")
• Internal Database IDs: Use our internal numeric IDs prefixed with "pf_" (e.g., "pf_456" for internal ID 456)

Example Workflow:

• Import article with correlationId: "your-cms-article-001"
• We store this correlation and return our internal articleId: 789
• Later, update the same article using either:
• Your correlation ID: "your-cms-article-001"
• Our internal ID: "pf_789"

Content Management

• Multilingual Support: Each article can have content in multiple languages
• Versioning: Content can have multiple versions with the ability to create new versions
• Publishing Control: Each content version can be published or unpublished independently

Import Behavior

• Create or Update: Articles are created if they don't exist, updated if they do (based on correlation ID)
• Partial Updates: Behavior differs between creating new items vs updating existing ones
• Batch Processing: Multiple articles can be imported in a single request

Partial Updates Explained

When Creating New Articles:

• Included fields will have the value you specify
• Non-included fields will use system default values

When Updating Existing Articles:

• Only fields you provide in the request are updated
• Missing fields keep their current values unchanged
• Allows selective updates without affecting other properties

Example - Creating New Article:

Request:

{
  "correlationId": "new-article-001",
  "contents": [
    {
      "lang": "en",
      "title": "My New Article",
      "format": "markdown"
    }
  ]
}

Response - Full article created with defaults:

{
  "errors": [],
  "results": [
    {
      "correlationId": "new-article-001",
      "articleId": 123,
      "status": "created",
      "categoryId": null,               // default: no category
      "isPrivate": false,              // default: public
      "isHidden": false,               // default: visible
      "isFeatured": false,             // default: not featured
      "featuredOrder": 0,              // default: not featured
      "order": 1,                      // default: auto-assigned
      "version": "v1",
      "alternateSlugs": null,          // default: no alternate slugs
      "contents": [
        {
          "correlationId": null,       // default: no correlation ID
          "lang": "en",                // as specified
          "contentId": 456,
          "slug": "my-new-article",    // default: auto-generated from title
          "status": "created",
          "published": false,          // default: unpublished
          "title": "My New Article",  // as specified
          "content": null,            // default: empty content
          "keywords": null,           // default: no keywords
          "lead": null                // default: no lead
        }
      ],
      "errors": []
    }
  ]
}

Example - Updating Existing Article:

Request:

{
  "correlationId": "existing-article-001",
  "isFeatured": true,
  "contents": [
    {
      "correlationId": "existing-content-en",
      "lang": "en",
      "publishStatus": "published"
    }
  ]
}

Response - Only specified fields updated:

{
  "errors": [],
  "results": [
    {
      "correlationId": "existing-article-001",
      "articleId": 789,
      "status": "updated",
      "categoryId": 456,               // unchanged: kept existing value
      "isPrivate": false,              // unchanged: kept existing value
      "isHidden": false,               // unchanged: kept existing value
      "isFeatured": true,              // updated: changed to specified value
      "featuredOrder": 0,              // unchanged: kept existing value
      "order": 5,                      // unchanged: kept existing value
      "version": "v1",                 // unchanged: kept existing value
      "alternateSlugs": "{\"en\":[\"old-slug\"]}", // unchanged: kept existing value
      "contents": [
        {
          "correlationId": "existing-content-en",
          "lang": "en",                // unchanged: kept existing value
          "contentId": 999,
          "slug": "existing-article",  // unchanged: kept existing value
          "status": "updated",
          "published": true,           // updated: changed to specified value
          "title": "Existing Article Title", // unchanged: kept existing value
          "content": "Original content...",   // unchanged: kept existing value
          "keywords": "original, keywords",  // unchanged: kept existing value
          "lead": "Original lead text"       // unchanged: kept existing value
        }
      ],
      "errors": []
    }
  ]
}

Only the fields you specified (isFeatured and publishStatus) were updated. All other fields retained their existing values.

Error Handling

The API uses standard HTTP status codes and provides two types of error information:

HTTP Status Codes

• 200 OK: Request successful (or partial success with ignoreImportErrors: true)
• 400 Bad Request: Validation errors or malformed request
• 401 Unauthorized: Invalid or missing API token
• 404 Not Found: Resource not found
• 500 Internal Server Error: Server error

Error Types

1. API Error Codes: Critical errors that prevent processing (return HTTP error status)

{
  "error": "Authentication required or invalid API token"
}

2. Processing Errors: Issues with specific items during import (returned in errors[] array)

{
  "errors": [
    "Article with correlation ID 'missing-article' not found",
    "Language 'en' is required for content"
  ],
  "results": [...]
}

Ignore Errors Configuration

Without ignoreImportErrors (default behavior):

• Processing errors return 400 Bad Request status
• Import stops on first serious error

With ignoreImportErrors: true:

• Processing errors return 200 OK status
• Successful items are processed and saved
• Failed items are skipped but errors are still collected in the errors[] array for reporting
• Allows partial imports to succeed while providing full error details

Example with ignored errors:

{
  "errors": [
    "Article 'invalid-article' failed validation",
    "Content for 'article-2' missing required title"
  ],
  "results": [
    {
      "correlationId": "valid-article",
      "status": "created",
      "articleId": 123
    }
  ]
}

Response Format

All successful responses follow a consistent format with results and error collections:

{
  "errors": [],
  "results": [
    {
      "correlationId": "article-001",
      "articleId": 123,
      "status": "created",
      "contents": [
        {
          "lang": "en",
          "contentId": 456,
          "slug": "getting-started",
          "status": "created",
          "published": true
        }
      ],
      "errors": []
    }
  ]
}

Rate Limiting

The API implements rate limiting to ensure fair usage and system stability. Please consult the detailed guide on rate limits, quotas, and best practices.

Import Limits

Some endpoints have specific content limits per request:

Article Import (/import):

• Maximum 50 articles per import request
• Maximum 20 content languages per article
• Batch requests wisely to stay within these limits

Example of maximum batch size:

{
  "articles": [
    // ... up to 50 articles maximum
  ]
}

Each article can have content in up to 20 different languages:

{
  "correlationId": "multilingual-article",
  "contents": [
    // ... up to 20 content objects (different languages) maximum
  ]
}

Next Steps

• Review the detailed documentation for each endpoint
• Test the API using the provided examples
• Integrate the API into your content management workflow
• Set up error handling and monitoring for production use