Introduction

Welcome to the Knowledge Base (KB) API documentation. This API provides programmatic access to manage users and articles within the KB system.

We adhere to RESTful principles, using standard HTTP methods (GET, POST, PUT, DELETE) and returning responses in JSON format.

Authentication

All requests to the KB API must be authenticated. Authentication is handled via an API Key provided in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with your actual API key obtained from the dashboard.

Users

Endpoints for managing user accounts.

GET /users

Retrieve a list of all users.

Query Parameters

  • limit [integer] Optional - Maximum number of users to return.
  • offset [integer] Optional - Number of users to skip.

Success Response (200 OK)

Show Example
[
  {
    "id": "usr_123",
    "username": "johndoe",
    "email": "john.doe@example.com",
    "createdAt": "2023-10-27T10:00:00Z",
    "updatedAt": "2023-10-27T10:00:00Z"
  },
  {
    "id": "usr_456",
    "username": "janedoe",
    "email": "jane.doe@example.com",
    "createdAt": "2023-10-27T11:00:00Z",
    "updatedAt": "2023-10-27T11:00:00Z"
  }
]
GET /users/{id}

Retrieve a specific user by their ID.

Path Parameters

  • id [string] Required - The unique identifier of the user.

Success Response (200 OK)

Show Example
{
  "id": "usr_123",
  "username": "johndoe",
  "email": "john.doe@example.com",
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:00:00Z"
}

Error Response (404 Not Found)

Show Example
{
  "error": "User not found"
}
POST /users

Create a new user.

Request Body

  • username [string] Required - The desired username.
  • email [string] Required - The user's email address.
  • password [string] Required - The user's password.

Success Response (201 Created)

Show Example
{
  "id": "usr_789",
  "username": "newuser",
  "email": "new.user@example.com",
  "createdAt": "2023-10-27T12:00:00Z",
  "updatedAt": "2023-10-27T12:00:00Z"
}

Error Response (400 Bad Request)

Show Example
{
  "error": "Invalid input: Username already exists."
}
PUT /users/{id}

Update an existing user's information.

Path Parameters

  • id [string] Required - The unique identifier of the user to update.

Request Body

  • username [string] Optional - The new username.
  • email [string] Optional - The new email address.

Success Response (200 OK)

Show Example
{
  "id": "usr_123",
  "username": "johndoe_updated",
  "email": "john.doe.updated@example.com",
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T13:00:00Z"
}

Error Response (404 Not Found)

Show Example
{
  "error": "User not found"
}
DELETE /users/{id}

Delete a user.

Path Parameters

  • id [string] Required - The unique identifier of the user to delete.

Success Response (204 No Content)

The user was successfully deleted.

Error Response (404 Not Found)

Show Example
{
  "error": "User not found"
}

Articles

Endpoints for managing knowledge base articles.

GET /articles

Retrieve a list of all articles.

Query Parameters

  • category [string] Optional - Filter articles by category.
  • search [string] Optional - Search query for title or content.
  • limit [integer] Optional - Maximum number of articles to return.
  • offset [integer] Optional - Number of articles to skip.

Success Response (200 OK)

Show Example
[
  {
    "id": "art_abc",
    "title": "Getting Started with the KB API",
    "category": "API Usage",
    "authorId": "usr_123",
    "createdAt": "2023-10-26T09:00:00Z",
    "updatedAt": "2023-10-26T09:00:00Z"
  },
  {
    "id": "art_def",
    "title": "Troubleshooting Common Issues",
    "category": "Troubleshooting",
    "authorId": "usr_456",
    "createdAt": "2023-10-27T14:00:00Z",
    "updatedAt": "2023-10-27T14:00:00Z"
  }
]
GET /articles/{id}

Retrieve a specific article by its ID.

Path Parameters

  • id [string] Required - The unique identifier of the article.

Success Response (200 OK)

Show Example
{
  "id": "art_abc",
  "title": "Getting Started with the KB API",
  "category": "API Usage",
  "content": "This article explains how to authenticate and make your first API call...",
  "authorId": "usr_123",
  "createdAt": "2023-10-26T09:00:00Z",
  "updatedAt": "2023-10-26T09:00:00Z"
}

Error Response (404 Not Found)

Show Example
{
  "error": "Article not found"
}
POST /articles

Create a new article.

Request Body

  • title [string] Required - The title of the article.
  • category [string] Required - The category of the article.
  • content [string] Required - The main content of the article.
  • authorId [string] Required - The ID of the user who created the article.

Success Response (201 Created)

Show Example
{
  "id": "art_ghi",
  "title": "New Article Title",
  "category": "General",
  "content": "Content for the new article.",
  "authorId": "usr_123",
  "createdAt": "2023-10-27T15:00:00Z",
  "updatedAt": "2023-10-27T15:00:00Z"
}

Error Response (400 Bad Request)

Show Example
{
  "error": "Invalid input: Missing required fields."
}
PUT /articles/{id}

Update an existing article.

Path Parameters

  • id [string] Required - The unique identifier of the article to update.

Request Body

  • title [string] Optional - The new title.
  • category [string] Optional - The new category.
  • content [string] Optional - The new content.

Success Response (200 OK)

Show Example
{
  "id": "art_abc",
  "title": "Getting Started with the KB API (Revised)",
  "category": "API Usage",
  "content": "This article explains how to authenticate and make your first API call. Updated content here.",
  "authorId": "usr_123",
  "createdAt": "2023-10-26T09:00:00Z",
  "updatedAt": "2023-10-27T16:00:00Z"
}

Error Response (404 Not Found)

Show Example
{
  "error": "Article not found"
}
DELETE /articles/{id}

Delete an article.

Path Parameters

  • id [string] Required - The unique identifier of the article to delete.

Success Response (204 No Content)

The article was successfully deleted.

Error Response (404 Not Found)

Show Example
{
  "error": "Article not found"
}

Endpoints Overview

Here's a summary of all available endpoints:

GET /users

List all users.

GET /users/{id}

Get a specific user.

POST /users

Create a new user.

PUT /users/{id}

Update a user.

DELETE /users/{id}

Delete a user.

GET /articles

List all articles.

GET /articles/{id}

Get a specific article.

POST /articles

Create a new article.

PUT /articles/{id}

Update an article.

DELETE /articles/{id}

Delete an article.