Knowledge Base API Reference

API Overview

Welcome to the Knowledge Base API reference. This API allows you to programmatically access and manage all content within the Knowledge Base platform. You can retrieve articles, categories, manage user data, and perform searches.

All API requests should be made to the base URL: https://api.knowledgebase.example.com/v1

Authentication is handled via API keys passed in the Authorization header as a Bearer token.

Articles API

GET /articles

Retrieve a list of all articles. Supports pagination and filtering.

Query Parameters

Name Type Description Required
page integer The page number for pagination. No
limit integer The number of articles to return per page. No
category_id integer Filter articles by category ID. No
status string Filter by article status (e.g., 'published', 'draft'). No

Responses

Code Description Schema
200 OK Successfully retrieved list of articles. See response schema below.
401 Unauthorized Authentication failed. N/A
500 Internal Server Error Server error. N/A 
{
  "data": [
    {
      "id": 1,
      "title": "Getting Started with the API",
      "slug": "getting-started-api",
      "category_id": 5,
      "author_id": 101,
      "status": "published",
      "created_at": "2023-10-27T10:00:00Z",
      "updated_at": "2023-10-27T10:00:00Z"
    }
    // ... more articles
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 10,
    "per_page": 20,
    "total_items": 200
  }
}
GET /articles/{id}

Retrieve a specific article by its ID.

Path Parameters

Name Type Description Required
id integer The unique identifier of the article. Yes

Responses

Code Description Schema
200 OK Successfully retrieved the article. See response schema below.
404 Not Found Article not found. N/A
401 Unauthorized Authentication failed. N/A 
{
  "id": 1,
  "title": "Getting Started with the API",
  "slug": "getting-started-api",
  "content": "
This article provides a comprehensive guide...
",
  "category_id": 5,
  "author_id": 101,
  "status": "published",
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T10:00:00Z",
  "tags": ["api", "getting-started", "documentation"]
}
POST /articles

Create a new article.

Request Body

Field Type Description Required
title string The title of the article. Yes
content string The main content of the article (HTML or Markdown). Yes
category_id integer The ID of the category the article belongs to. Yes
status string The initial status of the article (e.g., 'draft', 'published'). No (defaults to 'draft')
tags array of strings Optional tags for the article. No

Responses

Code Description Schema
201 Created Article successfully created. See response schema below.
400 Bad Request Invalid input data. N/A
401 Unauthorized Authentication failed. N/A 
{
  "id": 55,
  "title": "New Feature Explained",
  "slug": "new-feature-explained",
  "category_id": 7,
  "author_id": 101,
  "status": "draft",
  "created_at": "2023-10-27T11:30:00Z",
  "updated_at": "2023-10-27T11:30:00Z",
  "tags": ["new feature", "release notes"]
}
PUT /articles/{id}

Update an existing article.

Path Parameters

Name Type Description Required
id integer The unique identifier of the article to update. Yes

Request Body

All fields are optional. Only provide fields you wish to update.

Field Type Description Required
title string The new title of the article. No
content string The new content of the article. No
category_id integer The new category ID. No
status string The new status of the article. No
tags array of strings The new list of tags. No

Responses

Code Description Schema
200 OK Article successfully updated. See response schema below (updated article).
400 Bad Request Invalid input data. N/A
404 Not Found Article not found. N/A
401 Unauthorized Authentication failed. N/A 
{
  "id": 1,
  "title": "Getting Started with the API (Updated)",
  "slug": "getting-started-api",
  "content": "
This article provides a comprehensive guide...
",
  "category_id": 5,
  "author_id": 101,
  "status": "published",
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T11:45:00Z",
  "tags": ["api", "getting-started", "documentation", "updated"]
}
DELETE /articles/{id}

Delete a specific article.

Path Parameters

Name Type Description Required
id integer The unique identifier of the article to delete. Yes

Responses

Code Description Schema
204 No Content Article successfully deleted. N/A
404 Not Found Article not found. N/A
401 Unauthorized Authentication failed. N/A

Categories API

GET /categories

Retrieve a list of all categories.

Responses

Code Description Schema
200 OK Successfully retrieved list of categories. See response schema below.
401 Unauthorized Authentication failed. N/A 
{
  "data": [
    {"id": 1, "name": "Getting Started", "slug": "getting-started"},
    {"id": 2, "name": "API Usage", "slug": "api-usage"},
    {"id": 3, "name": "Troubleshooting", "slug": "troubleshooting"}
    // ... more categories
  ]
}
GET /categories/{id}/articles

Retrieve all articles within a specific category.

Path Parameters

Name Type Description Required
id integer The ID of the category. Yes

Responses

Code Description Schema
200 OK Successfully retrieved articles for the category. See Article List Schema.
404 Not Found Category not found. N/A
POST /categories

Create a new category.

Request Body

Field Type Description Required
name string The name of the category. Yes
parent_id integer Optional ID of the parent category for nesting. No

Responses

Code Description Schema
201 Created Category successfully created. {"id": 4, "name": "New Topic", "slug": "new-topic", "parent_id": null}
400 Bad Request Invalid input data (e.g., missing name). N/A

Users API

GET /users

Retrieve a list of users. Requires admin privileges.

Responses

Code Description Schema
200 OK Successfully retrieved list of users. See response schema below.
401 Unauthorized Authentication failed or insufficient permissions. N/A 
{
  "data": [
    {"id": 101, "username": "admin_user", "email": "admin@example.com", "role": "admin"},
    {"id": 102, "username": "content_creator", "email": "content@example.com", "role": "editor"}
    // ... more users
  ]
}
GET /users/{id}

Retrieve a specific user by their ID.

Path Parameters

Name Type Description Required
id integer The unique identifier of the user. Yes

Responses

Code Description Schema
200 OK Successfully retrieved user details. See response schema below.
404 Not Found User not found. N/A
401 Unauthorized Authentication failed. N/A 
{
  "id": 101,
  "username": "admin_user",
  "email": "admin@example.com",
  "role": "admin",
  "created_at": "2023-01-15T08:30:00Z"
}