Introduction

Welcome to the Knowledge Base API documentation. This API provides endpoints to manage and retrieve articles and categories within your knowledge base.

Our API follows RESTful principles and uses JSON for request and response bodies. Authentication is handled via API keys, which should be included in the X-API-Key header for all requests.

Base URL: /kb/api/v1

Articles

GET /articles

Retrieves a list of all articles in the knowledge base.

Query Parameters

Name Type Description Required
category String Filter articles by category slug. No
search String Full-text search across article titles and content. No
limit Integer Maximum number of articles to return. No
offset Integer Number of articles to skip. No

Responses

Status Code Content Type Description
200 OK application/json An array of article objects.
401 Unauthorized application/json Invalid or missing API key.

Example Response

JSON
[
    {
        "id": "a1b2c3d4",
        "title": "Getting Started with the API",
        "slug": "getting-started-api",
        "category": "api-usage",
        "created_at": "2023-10-27T10:00:00Z",
        "updated_at": "2023-10-27T10:00:00Z"
    },
    {
        "id": "e5f6g7h8",
        "title": "Understanding Authentication",
        "slug": "understanding-authentication",
        "category": "security",
        "created_at": "2023-10-27T11:30:00Z",
        "updated_at": "2023-10-27T11:30:00Z"
    }
]

Create Article

POST /articles

Creates a new article in the knowledge base.

Request Body

{
    "title": "string (required)",
    "content": "string (required)",
    "category_id": "string (required)",
    "tags": ["string"]
}

Responses

Status Code Content Type Description
201 Created application/json The newly created article object.
400 Bad Request application/json Invalid input data.
401 Unauthorized application/json Invalid or missing API key.
404 Not Found application/json Category not found.

Example Request

JSON
{
    "title": "How to Use the Search Feature",
    "content": "This article explains how to effectively use the search functionality to find relevant information in the knowledge base.",
    "category_id": "cat-search-tips",
    "tags": ["search", "guide", "kb"]
}

Example Response

JSON
{
    "id": "i9j8k7l6",
    "title": "How to Use the Search Feature",
    "slug": "how-to-use-search-feature",
    "content": "This article explains how to effectively use the search functionality to find relevant information in the knowledge base.",
    "category_id": "cat-search-tips",
    "tags": ["search", "guide", "kb"],
    "created_at": "2023-10-27T14:00:00Z",
    "updated_at": "2023-10-27T14:00:00Z"
}

Get Article by ID

GET /articles/{id}

Retrieves a specific article by its unique ID.

Path Parameters

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

Responses

Status Code Content Type Description
200 OK application/json The article object.
401 Unauthorized application/json Invalid or missing API key.
404 Not Found application/json Article with the specified ID not found.

Example Response

JSON
{
    "id": "a1b2c3d4",
    "title": "Getting Started with the API",
    "slug": "getting-started-api",
    "content": "This is the detailed content of the article. It can include markdown or HTML...",
    "category_id": "cat-api",
    "tags": ["api", "guide"],
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T10:00:00Z"
}

Update Article

PUT /articles/{id}

Updates an existing article by its unique ID. All fields are optional and will only be updated if provided.

Path Parameters

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

Request Body

{
    "title": "string",
    "content": "string",
    "category_id": "string",
    "tags": ["string"]
}

Responses

Status Code Content Type Description
200 OK application/json The updated article object.
400 Bad Request application/json Invalid input data.
401 Unauthorized application/json Invalid or missing API key.
404 Not Found application/json Article or category not found.

Example Request

JSON
{
    "content": "Updated content for the article, explaining new features.",
    "tags": ["api", "guide", "new-features"]
}

Example Response

JSON
{
    "id": "a1b2c3d4",
    "title": "Getting Started with the API",
    "slug": "getting-started-api",
    "content": "Updated content for the article, explaining new features...",
    "category_id": "cat-api",
    "tags": ["api", "guide", "new-features"],
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T15:00:00Z"
}

Delete Article

DELETE /articles/{id}

Deletes a specific article by its unique ID.

Path Parameters

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

Responses

Status Code Content Type Description
204 No Content Article deleted successfully.
401 Unauthorized application/json Invalid or missing API key.
404 Not Found application/json Article with the specified ID not found.

Categories

GET /categories

Retrieves a list of all categories.

Responses

Status Code Content Type Description
200 OK application/json An array of category objects.
401 Unauthorized application/json Invalid or missing API key.

Example Response

JSON
[
    {
        "id": "cat-api",
        "name": "API Usage",
        "slug": "api-usage",
        "description": "Articles related to how to use our APIs."
    },
    {
        "id": "cat-security",
        "name": "Security",
        "slug": "security",
        "description": "Information about security best practices."
    }
]

Create Category

POST /categories

Creates a new category.

Request Body

{
    "name": "string (required)",
    "description": "string (optional)"
}

Responses

Status Code Content Type Description
201 Created application/json The newly created category object.
400 Bad Request application/json Invalid input data.
401 Unauthorized application/json Invalid or missing API key.

Example Request

JSON
{
    "name": "Troubleshooting",
    "description": "Common issues and their solutions."
}

Example Response

JSON
{
    "id": "cat-troubleshooting",
    "name": "Troubleshooting",
    "slug": "troubleshooting",
    "description": "Common issues and their solutions.",
    "created_at": "2023-10-27T16:00:00Z"
}