API Documentation

Overview

This API provides programmatic access to our Knowledge Base platform. All requests are made over HTTPS and return JSON.

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

All timestamps are in ISO‑8601 format (UTC).

Authentication

Use Bearer Token authentication. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Example using curl:

curl -H "Authorization: Bearer abc123xyz" https://api.example.com/v1/articles

Endpoints

List Articles

GET /articles

Returns a paginated list of articles.

{
  "page": 1,
  "per_page": 20,
  "total": 342,
  "articles": [
    {
      "id": "a1b2c3",
      "title": "Getting Started",
      "slug": "getting-started",
      "summary": "An introduction to the platform."
    }
  ]
}

Get Single Article

GET /articles/{id}

Retrieve detailed information about a specific article.

curl -H "Authorization: Bearer abc123xyz" https://api.example.com/v1/articles/a1b2c3

Create Article

POST /articles

Creates a new article. JSON body required.

{
  "title": "New Article",
  "content": "# Markdown Content\\n\\nYour article body here.",
  "tags": ["api","docs"]
}

Error Handling

The API uses standard HTTP status codes. Errors return a JSON payload:

{
  "error": "InvalidRequest",
  "message": "The 'page' parameter must be a positive integer.",
  "status": 400
}

• 400 Bad Request – Invalid parameters.
• 401 Unauthorized – Missing or invalid API key.
• 403 Forbidden – Insufficient permissions.
• 404 Not Found – Resource does not exist.
• 429 Too Many Requests – Rate limit exceeded.
• 500 Internal Server Error – Unexpected server error.

Rate Limiting

Each API key is limited to 120 requests per minute. Exceeding this limit returns a 429 response with the following headers:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1696802400

Implement exponential back‑off when retrying.

Changelog

• v1.2.0 – Added article tagging, improved pagination.
• v1.1.0 – Introduced webhook support.
• v1.0.0 – Initial release.