Knowledge Base API Documentation

Version 1.0.0

Introduction

Welcome to the Knowledge Base API documentation. This API allows you to manage and retrieve information stored within our knowledge base. You can perform operations such as fetching articles, creating new content, updating existing entries, and searching for specific information.

The API follows RESTful principles and uses JSON for request and response bodies. All requests should be made to the base URL: https://api.example.com/kb/v1.

Authentication

All requests to the Knowledge Base API must be authenticated. Currently, we support API key authentication.

Include your API key in the Authorization header of your request:

Authorization: Bearer YOUR_API_KEY

If authentication fails, you will receive a 401 Unauthorized response.

API Endpoints

GET /items

Retrieves a list of all knowledge base items.

Parameters

Optional query parameters:

Name Type Description Required
limit Integer Maximum number of items to return. Defaults to 20. No
offset Integer Number of items to skip before returning results. Defaults to 0. No
sort String Field to sort by (e.g., createdAt, title). No
order String Sort order: asc or desc. Defaults to desc. No

Responses

200 OK

A JSON array of knowledge base items.

[
  {
    "id": "a1b2c3d4",
    "title": "Getting Started with the API",
    "summary": "An overview of how to use our API.",
    "tags": ["api", "guide", "getting started"],
    "createdAt": "2023-10-27T10:00:00Z",
    "updatedAt": "2023-10-27T10:00:00Z"
  },
  {
    "id": "e5f6g7h8",
    "title": "Common API Errors",
    "summary": "Explains common error codes and their meanings.",
    "tags": ["api", "errors", "troubleshooting"],
    "createdAt": "2023-10-26T14:30:00Z",
    "updatedAt": "2023-10-26T14:30:00Z"
  }
]

GET /items/{itemId}

Retrieves a single knowledge base item by its unique ID.

Parameters

Name Type Description Required
itemId String The unique identifier of the knowledge base item. Yes

Responses

200 OK

A JSON object representing the knowledge base item.

{
  "id": "a1b2c3d4",
  "title": "Getting Started with the API",
  "content": "This document provides a comprehensive guide...",
  "tags": ["api", "guide", "getting started"],
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:00:00Z",
  "author": "Jane Doe"
}
404 Not Found

If the item with the specified ID does not exist.

POST /items

Creates a new knowledge base item.

Request Body

The request body should be a JSON object containing the details of the new item.

{
  "title": "New Feature Announcement",
  "content": "We are excited to announce our latest feature...",
  "tags": ["features", "announcements"]
}

Responses

201 Created

The newly created knowledge base item, including its generated ID.

{
  "id": "x9y8z7w6",
  "title": "New Feature Announcement",
  "content": "We are excited to announce our latest feature...",
  "tags": ["features", "announcements"],
  "createdAt": "2023-10-28T09:15:00Z",
  "updatedAt": "2023-10-28T09:15:00Z"
}
400 Bad Request

If the request body is invalid or missing required fields.

PUT /items/{itemId}

Updates an existing knowledge base item.

Parameters

Name Type Description Required
itemId String The unique identifier of the knowledge base item to update. Yes

Request Body

The request body should be a JSON object containing the fields to update.

{
  "title": "Updated Feature Announcement",
  "content": "We have made improvements to our latest feature...",
  "tags": ["features", "updates"]
}

Responses

200 OK

The updated knowledge base item.

{
  "id": "x9y8z7w6",
  "title": "Updated Feature Announcement",
  "content": "We have made improvements to our latest feature...",
  "tags": ["features", "updates"],
  "createdAt": "2023-10-28T09:15:00Z",
  "updatedAt": "2023-10-28T11:05:00Z"
}
400 Bad Request

If the request body is invalid.

404 Not Found

If the item with the specified ID does not exist.

DELETE /items/{itemId}

Deletes a knowledge base item.

Parameters

Name Type Description Required
itemId String The unique identifier of the knowledge base item to delete. Yes

Responses

204 No Content

Indicates that the item was successfully deleted.

404 Not Found

If the item with the specified ID does not exist.

GET /search

Searches knowledge base items based on keywords.

Parameters

Name Type Description Required
q String The search query string. Yes
limit Integer Maximum number of results to return. No
offset Integer Number of results to skip. No

Responses

200 OK

A JSON array of knowledge base items matching the search query.

[
  {
    "id": "a1b2c3d4",
    "title": "Getting Started with the API",
    "summary": "An overview of how to use our API.",
    "tags": ["api", "guide", "getting started"],
    "createdAt": "2023-10-27T10:00:00Z",
    "updatedAt": "2023-10-27T10:00:00Z"
  }
]
400 Bad Request

If the query parameter 'q' is missing.

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. Error responses will be in JSON format and include a descriptive message.

Status Code Meaning Example Response
400 Bad Request The request was malformed or contained invalid parameters. 
{
  "error": "Bad Request",
  "message": "Invalid parameter type for 'limit'."
}
401 Unauthorized Authentication credentials were missing or invalid. 
{
  "error": "Unauthorized",
  "message": "API key is missing or invalid."
}
403 Forbidden The authenticated user does not have permission to perform the action. 
{
  "error": "Forbidden",
  "message": "You do not have permission to delete this item."
}
404 Not Found The requested resource could not be found. 
{
  "error": "Not Found",
  "message": "The item with ID 'xyz123' was not found."
}
500 Internal Server Error An unexpected error occurred on the server. 
{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred. Please try again later."
}