Knowledge Base API Documentation

Advanced API Reference

This section provides detailed documentation for the advanced endpoints of our Knowledge Base API. These endpoints allow for more granular control and data manipulation.

GET /kb/advanced/api/articles

Retrieves a list of all articles available in the knowledge base.

Query Parameters

Name Type Required Description
category string false Filter articles by a specific category (e.g., 'api', 'configuration').
sort_by string false Field to sort results by (e.g., 'title', 'date_created').
order string false Order of sorting ('asc' or 'desc'). Defaults to 'asc'.
limit integer false Maximum number of articles to return.
offset integer false Number of articles to skip before starting to collect the result set.

Successful Response (200 OK)

Returns a JSON object containing an array of article objects.

[
    {
        "id": "art_123",
        "title": "Understanding API Endpoints",
        "category": "api",
        "author": "Jane Doe",
        "date_created": "2023-10-26T10:00:00Z",
        "summary": "A comprehensive guide to how our API endpoints are structured..."
    },
    {
        "id": "art_456",
        "title": "Advanced Configuration Options",
        "category": "configuration",
        "author": "John Smith",
        "date_created": "2023-10-25T14:30:00Z",
        "summary": "Explore advanced settings for customizing your experience."
    }
]

Example Usage

curl -X GET "/kb/advanced/api/articles?category=api&sort_by=date_created&order=desc&limit=10"

GET /kb/advanced/api/articles/{article_id}

Retrieves a specific article by its unique ID.

Path Parameters

Name Type Required Description
article_id string true The unique identifier of the article.

Successful Response (200 OK)

Returns a JSON object representing the requested article.

{
    "id": "art_123",
    "title": "Understanding API Endpoints",
    "category": "api",
    "author": "Jane Doe",
    "date_created": "2023-10-26T10:00:00Z",
    "content": "
API Endpoint Structure
\n
Our API follows RESTful principles...
\n
Base URL
\n
https://api.yourkb.com/v1
\n
Common Conventions
\n
    \n    
  • Use HTTPS.
    • \n    
  • Use JSON for request and response bodies.
    • \n    
  • Requests should include an Authorization header.
    • \n
"
}

Error Response (404 Not Found)

Returned if the specified article ID does not exist.

{
    "error": "Article not found",
    "message": "No article found with the ID: art_999"
}

Example Usage

curl -X GET "/kb/advanced/api/articles/art_123"

POST /kb/advanced/api/articles

Creates a new article in the knowledge base.

Request Body (JSON)

Field Type Required Description
title string true The title of the new article.
category string true The category for the article.
content string true The main content of the article (can be HTML or Markdown).
tags array of strings false Optional tags to associate with the article.

Successful Response (201 Created)

Returns the newly created article object with its assigned ID.

{
    "id": "art_789",
    "title": "New API Feature Announcement",
    "category": "api",
    "author": "Admin",
    "date_created": "2023-10-27T09:15:00Z",
    "content": "
Announcing the release of our new search functionality!
",
    "tags": ["new feature", "search"]
}

Error Response (400 Bad Request)

Returned if required fields are missing or data is invalid.

{
    "error": "Bad Request",
    "message": "Missing required field: title"
}

Example Usage

curl -X POST \
  /kb/advanced/api/articles \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "New API Feature Announcement",
    "category": "api",
    "content": "
Announcing the release of our new search functionality!
",
    "tags": ["new feature", "search"]
  }'

PUT /kb/advanced/api/articles/{article_id}

Updates an existing article by its unique ID. Replaces the entire article content.

Path Parameters

Name Type Required Description
article_id string true The unique identifier of the article to update.

Request Body (JSON)

All fields are optional, but at least one field must be provided for an update.

Field Type Required Description
title string false The new title of the article.
category string false The new category for the article.
content string false The new main content of the article.
tags array of strings false The new set of tags for the article.

Successful Response (200 OK)

Returns the updated article object.

{
    "id": "art_123",
    "title": "Updated API Endpoint Guide",
    "category": "api",
    "author": "Jane Doe",
    "date_created": "2023-10-26T10:00:00Z",
    "date_modified": "2023-10-27T11:00:00Z",
    "content": "
This guide has been updated with new examples.
",
    "tags": ["api", "guide", "updated"]
}

Error Response (404 Not Found)

Returned if the article ID does not exist.

{
    "error": "Article not found",
    "message": "No article found with the ID: art_999"
}

Example Usage

curl -X PUT \
  /kb/advanced/api/articles/art_123 \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Updated API Endpoint Guide",
    "content": "
This guide has been updated with new examples.
",
    "tags": ["api", "guide", "updated"]
  }'

DELETE /kb/advanced/api/articles/{article_id}

Deletes an article from the knowledge base by its unique ID.

Path Parameters

Name Type Required Description
article_id string true The unique identifier of the article to delete.

Successful Response (204 No Content)

Indicates that the article was successfully deleted. No response body is returned.

Error Response (404 Not Found)

Returned if the article ID does not exist.

{
    "error": "Article not found",
    "message": "No article found with the ID: art_999"
}

Example Usage

curl -X DELETE "/kb/advanced/api/articles/art_789"