API Reference

Checks the current authentication status.

Parameters:

• Authorization (header, optional): Bearer token for authenticated requests.

Responses:

• 200 OK: Authentication successful.

  
  {
    "authenticated": true,
    "user_id": "user_123",
    "scopes": ["read:content", "write:content"]
  }
                                  

• 401 Unauthorized: Missing or invalid credentials.

  
  {
    "error": "Unauthorized",
    "message": "Authentication token is invalid or expired."
  }
                                  

Logs in a user and returns an authentication token.

Request Body:

{
  "username": "string",
  "password": "string"
}
                    

Responses:

• 200 OK: Login successful. Returns an authentication token.

  
  {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600
  }
                                  

• 400 Bad Request: Invalid input.

  
  {
    "error": "Bad Request",
    "message": "Username and password are required."
  }
                                  

• 401 Unauthorized: Invalid credentials.

  
  {
    "error": "Unauthorized",
    "message": "Invalid username or password."
  }
                                  

Retrieves details for a specific user.

Parameters:

• user_id (path, required): The unique identifier of the user.
• Authorization (header, required): Bearer token for authenticated requests.

Responses:

• 200 OK: User details returned.

  
  {
    "user_id": "user_123",
    "username": "alice_wonder",
    "email": "alice@example.com",
    "full_name": "Alice Wonderland",
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T10:00:00Z"
  }
                                  

• 404 Not Found: User not found.
• 401 Unauthorized: Authentication required.

Retrieves a list of all users. Supports pagination.

Parameters:

• page (query, optional): The page number to retrieve (default: 1).
• limit (query, optional): The number of items per page (default: 20).
• Authorization (header, required): Bearer token for authenticated requests (admin scope).

Responses:

• 200 OK: List of users.

  
  {
    "users": [
      {"user_id": "user_123", "username": "alice_wonder", "email": "alice@example.com"},
      {"user_id": "user_456", "username": "bob_builder", "email": "bob@example.com"}
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_items": 100,
      "items_per_page": 20
    }
  }
                                  

• 401 Unauthorized: Authentication required.
• 403 Forbidden: User does not have permission.

Creates a new knowledge base article.

Request Body:

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

Responses:

• 201 Created: Article successfully created.

  
  {
    "article_id": "art_abc123",
    "title": "New Article Title",
    "created_at": "2023-10-27T11:00:00Z",
    "updated_at": "2023-10-27T11:00:00Z"
  }
                                  

• 400 Bad Request: Invalid input.
• 401 Unauthorized: Authentication required.

Retrieves a specific knowledge base article by its ID.

Parameters:

• article_id (path, required): The unique identifier of the article.
• Authorization (header, optional): Bearer token for authenticated requests.

Responses:

• 200 OK: Article found.

  
  {
    "article_id": "art_abc123",
    "title": "Existing Article",
    "content": "# Markdown Content\n\nThis is the **body** of the article.",
    "category_id": "cat_tech",
    "tags": ["api", "reference"],
    "created_at": "2023-10-27T11:00:00Z",
    "updated_at": "2023-10-27T12:30:00Z"
  }
                                  

• 404 Not Found: Article not found.

Searches for articles based on keywords and filters.

Parameters:

• q (query, required): The search query string.
• category (query, optional): Filter results by category ID.
• tag (query, optional): Filter results by tag.
• page (query, optional): The page number for results (default: 1).
• limit (query, optional): Number of results per page (default: 10).
• Authorization (header, optional): Bearer token for authenticated requests.

Responses:

• 200 OK: Search results.

  
  {
    "query": "api authentication",
    "results": [
      {
        "article_id": "art_auth001",
        "title": "API Authentication Methods",
        "snippet": "This article covers different ways to authenticate your API requests...",
        "score": 0.95
      },
      {
        "article_id": "art_token002",
        "title": "Understanding JWT Tokens",
        "snippet": "Learn about JSON Web Tokens (JWT) and how they are used in authentication...",
        "score": 0.92
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 3,
      "total_items": 30
    }
  }
                                  

• 400 Bad Request: Missing or invalid query parameter.

Retrieves a list of the most viewed articles.

Parameters:

• limit (query, optional): Number of top articles to retrieve (default: 10).
• Authorization (header, required): Bearer token for authenticated requests (analytics scope).

Responses:

• 200 OK: Popular articles.

  
  {
    "articles": [
      {"article_id": "art_xyz789", "title": "Getting Started with the KB API", "views": 5000},
      {"article_id": "art_abc123", "title": "Advanced API Usage", "views": 4500}
    ]
  }
                                  

• 401 Unauthorized: Authentication required.
• 403 Forbidden: User lacks necessary permissions.