API Documentation

Introduction

Welcome to the Knowledge Base (KB) API documentation. This API allows you to programmatically interact with the KB system, enabling you to manage articles, retrieve information, and integrate KB functionality into your applications.

The API follows RESTful principles and uses JSON for request and response bodies.

Base URL: https://api.kb.example.com/v1

Authentication

All requests to the KB API must be authenticated. We use API keys for authentication. Your API key should be included in the Authorization header as a Bearer token.

Authorization: Bearer YOUR_API_KEY

If you don't have an API key, please contact your administrator.

API Endpoints

`GET /articles`

Retrieves a list of all articles in the knowledge base.

Parameters:

Name	Type	Description	Required
`category`	`string`	Filter articles by category.	No
`search`	`string`	Search query for article titles and content.	No
`limit`	`integer`	Maximum number of articles to return. Default is 20.	No
`offset`	`integer`	Number of articles to skip. Useful for pagination. Default is 0.	No

Response:

Success (200 OK)

[
    {
        "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
        "title": "Getting Started with the KB API",
        "category": "API Usage",
        "created_at": "2023-10-27T10:00:00Z",
        "updated_at": "2023-10-27T10:00:00Z"
    },
    {
        "id": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
        "title": "Understanding Authentication",
        "category": "API Usage",
        "created_at": "2023-10-26T15:30:00Z",
        "updated_at": "2023-10-26T15:30:00Z"
    }
]

`GET /articles/{id}`

Retrieves a single article by its unique identifier.

Parameters:

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

Response:

Success (200 OK)

{
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "title": "Getting Started with the KB API",
    "content": "This article provides a comprehensive overview of how to get started with the KB API. It covers authentication, common endpoints, and best practices...",
    "category": "API Usage",
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T10:00:00Z"
}

Not Found (404 Not Found)

{
    "error": "Article not found",
    "message": "The article with the specified ID could not be found."
}

`POST /articles`

Creates a new article in the knowledge base.

Request Body:

{
    "title": "New Feature Announcement",
    "content": "Details about the latest feature release...",
    "category": "Announcements"
}

Response:

Created (201 Created)

{
    "id": "new-article-id-1234",
    "title": "New Feature Announcement",
    "content": "Details about the latest feature release...",
    "category": "Announcements",
    "created_at": "2023-10-28T09:00:00Z",
    "updated_at": "2023-10-28T09:00:00Z"
}

Bad Request (400 Bad Request)

{
    "error": "Invalid request body",
    "message": "Title and content are required fields."
}

`PUT /articles/{id}`

Updates an existing article.

Parameters:

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

Request Body:

Include only the fields you wish to update.

{
    "content": "Updated content for the article...",
    "category": "Tips & Tricks"
}

Response:

Success (200 OK)

{
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "title": "Getting Started with the KB API",
    "content": "Updated content for the article...",
    "category": "Tips & Tricks",
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-28T11:00:00Z"
}

Not Found (404 Not Found)

{
    "error": "Article not found",
    "message": "The article with the specified ID could not be found."
}

`DELETE /articles/{id}`

Deletes an article from the knowledge base.

Parameters:

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

Response:

Success (204 No Content)

No response body is returned on successful deletion.

Not Found (404 Not Found)

{
    "error": "Article not found",
    "message": "The article with the specified ID could not be found."
}

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 an error code and a descriptive message.

Common Error Codes:

400 Bad Request: The request was malformed or invalid.
401 Unauthorized: Authentication failed or was not provided.
403 Forbidden: The authenticated user does not have permission to perform the action.
404 Not Found: The requested resource was not found.
429 Too Many Requests: The rate limit has been exceeded.
500 Internal Server Error: An unexpected error occurred on the server.

Example of an error response:

{
    "error": "ResourceConflict",
    "message": "An article with this title already exists."
}

Rate Limiting

To ensure fair usage and system stability, the API enforces rate limits. Your current limit is 100 requests per minute.

If you exceed the rate limit, you will receive a 429 Too Many Requests response.

The following HTTP headers will be returned with each response to help you track your usage:

X-RateLimit-Limit: The maximum number of requests you can make per minute.
X-RateLimit-Remaining: The number of requests remaining in the current minute.
X-RateLimit-Reset: The time in UTC epoch seconds when the limit will reset.