API Reference

This page demonstrates the ApiBlock component — the primary tool for documenting REST API endpoints in ClearDocs. Each block renders a complete, interactive endpoint reference with the HTTP method, endpoint URL, headers, request body, response body, authentication requirements, rate limiting metadata, and auto-generated cURL examples. Use this page as both a working reference for the built-in authentication API and a template for documenting your own APIs.

Authentication

ClearDocs includes two built-in authentication endpoints for managing user sessions in private mode. These endpoints handle password verification, JWT session creation, and session cleanup.

Verify Password

The verify endpoint authenticates a visitor by checking the provided password against the server-side hash. On success, it sets a JWT session cookie that grants access to all documentation pages for 14 days. The endpoint is rate limited to prevent brute-force attacks.

Logout

The logout endpoint ends the current session by clearing the authentication cookie. It validates the request origin to prevent CSRF attacks and verifies that the session is authenticated before clearing.

Example: REST API Documentation

The following examples show how to document a typical REST API using ClearDocs components. Each endpoint demonstrates a different HTTP method with structured parameter and response field documentation alongside it. Use this section as a template when building your own API reference pages.

List Resources

Retrieve a paginated collection of resources. This example demonstrates the GET method with query parameters for filtering, sorting, and pagination — the most common pattern in REST API documentation.

Query Parameters

Response Fields

Create Resource

Create a new resource in the collection. This example demonstrates the POST method with a JSON request body, required and optional fields, and a 201 status code response.

Request Body Parameters

Update Resource

Replace an entire resource. This example demonstrates the PUT method, which requires all fields to be included in the request body — omitted fields are reset to their defaults.

Partial Update

Update specific fields without replacing the entire resource. This example demonstrates the PATCH method, which accepts a partial request body — only the included fields are modified.

Delete Resource

Permanently remove a resource. This example demonstrates the DELETE method with a confirmation response.

Deprecated Endpoint

ClearDocs supports marking endpoints as deprecated with optional migration guidance. Deprecated endpoints render with reduced opacity and a warning notice directing users to the replacement.

Usage

To use the ApiBlock component in your MDX files, pass all data props as JSON strings. The component parses, formats, and renders them automatically with syntax highlighting and interactive tabs.

Supported Props

The ApiBlock component accepts the following props for configuring endpoint documentation:

• method — GET | POST | PUT | PATCH | DELETE (required)
  • The HTTP method for the endpoint, rendered as a color-coded badge
• endpoint — string (required)
  • The API endpoint URL path, displayed prominently in the header
• description — string
  • Endpoint description text shown below the header
• headers — JSON string
  • Request headers as a JSON object string, rendered with syntax highlighting
• body — JSON string
  • JSON request body, auto-formatted with 2-space indentation
• response — JSON string
  • JSON response body for a single response
• statusCode — number
  • Response HTTP status code (default: 200)
• responses — JSON string (array)
  • Multiple responses displayed in a tabbed interface, each with statusCode, label, and body
• auth — string
  • Authentication type indicator: bearer, apiKey, basic, oauth2, or none
• authLabel — string
  • Custom auth label text that overrides the default label for the auth type
• deprecated — boolean
  • Mark the endpoint as deprecated, reducing opacity and showing a warning
• deprecationNote — string
  • Migration guidance text shown in a warning box when deprecated is true
• rateLimit — string or JSON
  • Rate limiting metadata, displayed as plain text or parsed from JSON with requests, window, and optional note fields
• baseUrl — string
  • Base URL prefix shown above the endpoint path in muted text
• codeExamples — JSON string (array)
  • Additional code examples beyond the auto-generated cURL, each with language, label, and code

Each method type renders with a distinct color: GET (blue), POST (green), PUT (amber), PATCH (purple), DELETE (red).

Companion Components

Use ParamField and ResponseField alongside ApiBlock to provide structured documentation for request parameters and response fields:

• name — string (required)
  • The parameter or field name, displayed in monospace font
• type — string
  • Data type label (string, integer, boolean, array, object, and more)
• location — string
  • Where the parameter is sent: path, query, body, or header
• required — boolean
  • Shows a red "required" label indicating the field must be provided
• defaultValue — string
  • Default value displayed as inline code when the field is omitted
• deprecated — boolean
  • Shows a red "deprecated" label indicating the field will be removed
• children — node
  • Description text that supports inline Markdown formatting