Developer API Documentation

Introduction

Welcome to the Knowledge Base Developer API. This API allows you to programmatically access and manage content within the KB platform. You can retrieve, create, update, and delete articles, manage categories, and perform searches.

Our API is RESTful and uses standard HTTP methods. Responses are returned in JSON format.

Authentication

All API requests must be authenticated. You can authenticate by providing an API key in the Authorization header of your request:

Authorization: Bearer YOUR_API_KEY

Obtain your API key from your account settings.

Note: For development purposes, you might use a sandbox environment. Ensure you are using the correct API key for the environment you are targeting.

GET /articles

Retrieves a list of all articles. Supports pagination and filtering.

Query Parameters

Name	Type	Description	Required
`page`	Integer	The page number to retrieve. Defaults to 1.	No
`limit`	Integer	The number of articles per page. Defaults to 20.	No
`category`	String	Filter articles by category slug or ID.	No

Example Request

GET /articles?page=2&limit=10&category=api-documentation

Example Response (200 OK)

Success

{
  "data": [
    {
      "id": "abc123xyz",
      "title": "Introduction to the KB API",
      "slug": "intro-kb-api",
      "author_id": "user456",
      "created_at": "2023-10-27T10:00:00Z",
      "updated_at": "2023-10-27T10:00:00Z"
    },
    {
      "id": "def456uvw",
      "title": "Authentication Methods",
      "slug": "auth-methods",
      "author_id": "user789",
      "created_at": "2023-10-27T11:30:00Z",
      "updated_at": "2023-10-27T11:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 2,
    "per_page": 10,
    "total_pages": 5,
    "total_items": 50
  }
}

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

Example Request

GET /articles/abc123xyz

Example Response (200 OK)

Success

{
  "id": "abc123xyz",
  "title": "Introduction to the KB API",
  "slug": "intro-kb-api",
  "content": "This article provides an overview of the KB API...",
  "author_id": "user456",
  "category": "api-documentation",
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T10:00:00Z",
  "tags": ["api", "documentation", "getting-started"]
}

Example Response (404 Not Found)

Not Found

{
  "error": "Article not found"
}

POST /articles

Creates a new article.

Request Body

The request body should be a JSON object containing the article details:

Name	Type	Description	Required
`title`	String	The title of the article.	Yes
`content`	String	The main content of the article. Supports Markdown.	Yes
`category`	String	The category slug for the article.	No
`tags`	Array of Strings	A list of tags for the article.	No

Example Request

POST /articles
Headers:
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

{
  "title": "New Feature Announcement",
  "content": "We are excited to announce our new **collaboration features**! \n\nThis will allow teams to work together more effectively.",
  "category": "updates",
  "tags": ["new-feature", "collaboration"]
}

Example Response (201 Created)

Created

{
  "id": "ghi789stu",
  "title": "New Feature Announcement",
  "slug": "new-feature-announcement",
  "author_id": "user123",
  "category": "updates",
  "created_at": "2023-10-27T14:00:00Z",
  "updated_at": "2023-10-27T14:00:00Z"
}

Example Response (400 Bad Request)

Bad Request

{
  "error": "Title is required"
}

PUT /articles/{id}

Updates an existing article by its unique ID.

Path Parameters

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

Request Body

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

Name	Type	Description	Required
`title`	String	The new title of the article.	No
`content`	String	The new main content of the article.	No
`category`	String	The new category slug for the article.	No
`tags`	Array of Strings	A new list of tags for the article.	No

Example Request

PUT /articles/abc123xyz
Headers:
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

{
  "content": "This article has been updated with new details about the API endpoints and response formats.",
  "tags": ["api", "documentation", "updates"]
}

Example Response (200 OK)

Success

{
  "id": "abc123xyz",
  "title": "Introduction to the KB API",
  "slug": "intro-kb-api",
  "content": "This article has been updated with new details about the API endpoints and response formats.",
  "author_id": "user456",
  "category": "api-documentation",
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T15:00:00Z",
  "tags": ["api", "documentation", "updates"]
}

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

Example Request

DELETE /articles/abc123xyz
Headers:
  Authorization: Bearer YOUR_API_KEY

Example Response (204 No Content)

Success

(No content in the response body)

Example Response (404 Not Found)

Not Found

{
  "error": "Article not found"
}

GET /categories

Retrieves a list of all available categories.

Example Request

GET /categories

Example Response (200 OK)

Success

{
  "data": [
    {
      "id": "cat001",
      "name": "Getting Started",
      "slug": "getting-started"
    },
    {
      "id": "cat002",
      "name": "API Documentation",
      "slug": "api-documentation"
    },
    {
      "id": "cat003",
      "name": "Troubleshooting",
      "slug": "troubleshooting"
    }
  ]
}

POST /categories

Creates a new category.

Request Body

Name	Type	Description	Required
`name`	String	The name of the category.	Yes

Example Request

POST /categories
Headers:
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

{
  "name": "New Category"
}

Example Response (201 Created)

Created

{
  "id": "cat004",
  "name": "New Category",
  "slug": "new-category"
}

GET /search/articles

Searches articles based on a query string.

Query Parameters

Name	Type	Description	Required
`q`	String	The search query.	Yes
`limit`	Integer	The maximum number of results to return. Defaults to 10.	No

Example Request

GET /search/articles?q=authentication&limit=5

Example Response (200 OK)

Success

{
  "data": [
    {
      "id": "def456uvw",
      "title": "Authentication Methods",
      "slug": "auth-methods",
      "score": 0.98
    },
    {
      "id": "ghi789stu",
      "title": "Secure API Authentication",
      "slug": "secure-api-auth",
      "score": 0.95
    }
  ],
  "query": "authentication"
}