Skip to main content
OwnDocs

API Reference

6 min read

This page shows the ApiBlock component, the main way to document REST API endpoints in OwnDocs. Each block renders an endpoint reference with the HTTP method, URL, headers, request body, response body, auth requirements, rate limit metadata, and a generated cURL example. Use the page as a working reference for the built-in auth API, or as a template for your own APIs.

Authentication

OwnDocs ships two built-in auth endpoints for managing user sessions in private mode. They check the password, create the JWT session, and clear it on logout.

Verify Password

The verify endpoint checks the password against the server-side hash. On success, it sets a JWT session cookie that grants access to every documentation page for 14 days. The endpoint is rate limited to stop brute-force attempts.

POST/api/auth/verifyNo auth required

Authenticate with the documentation site password. Returns a JWT session cookie on success. Rate limited to 5 attempts per IP with a 15-minute lockout.

Rate limit: 5 requests / 15 minutes (Per IP address)
Headers
Content-Typeapplication/json
Request Body
{ "password": "your-access-password" }
Request Example
curl -X POST "/api/auth/verify" \ -H "Content-Type: application/json" \ -d '{"password":"your-access-password"}'
Response
{ "success": true }

Logout

The logout endpoint ends the current session by clearing the auth cookie. It checks the request origin to stop CSRF attacks, and only clears the cookie after confirming the session is authenticated.

POST/api/auth/logoutBearer Token

End the current session and clear the authentication cookie.

Request Example
curl -X POST "/api/auth/logout"
Response200
{ "success": true }

Example: REST API Documentation

The examples below show how to document a typical REST API with OwnDocs components. Each endpoint uses a different HTTP method, with parameter and response field docs alongside it. Copy the shape of this section for your own API reference pages.

List Resources

Retrieve a paginated collection of resources. This example uses the GET method with query parameters for filtering, sorting, and pagination, the most common shape in REST API docs.

GEThttps://api.devops.bd/api/v1/documentsBearer Token

Retrieve a paginated list of documents. Supports filtering by status and sorting by creation date.

Headers
AuthorizationBearer <token>
Acceptapplication/json
Request Example
curl -X GET "https://api.devops.bd/api/v1/documents" \ -H "Authorization: Bearer <token>" \ -H "Accept: application/json"
Response200
{ "data": [ { "id": "doc_01", "title": "Getting Started Guide", "status": "published", "createdAt": "2026-03-24T12:00:00Z" }, { "id": "doc_02", "title": "API Integration", "status": "draft", "createdAt": "2026-03-23T09:30:00Z" } ], "meta": { "total": 42, "page": 1, "perPage": 20 } }

Query Parameters

pageintegerqueryDefault: 1

Page number for paginated results. The first page is 1.

perPageintegerqueryDefault: 20

Number of items returned per page. Maximum allowed value is 100.

statusstringquery

Filter results by document status. Allowed values: draft, published, archived. When omitted, documents of all statuses are returned.

sortstringqueryDefault: createdAt

Field to sort results by. Allowed values: createdAt, updatedAt, title. Results are sorted in descending order by default.

Response Fields

dataarrayrequired

Array of document objects matching the query. Each object contains the document ID, title, status, and creation timestamp.

meta.totalintegerrequired

Total number of documents matching the query across all pages.

meta.pageintegerrequired

Current page number in the paginated result set.

meta.perPageintegerrequired

Number of items included per page in the response.

Create Resource

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

POSThttps://api.devops.bd/api/v1/documentsBearer Token

Create a new document. The title field is required. Status defaults to draft if not specified.

Headers
AuthorizationBearer <token>
Content-Typeapplication/json
Request Body
{ "title": "New Document", "content": "Document body in Markdown format.", "status": "draft", "tags": [ "guide", "onboarding" ] }
Request Example
curl -X POST "https://api.devops.bd/api/v1/documents" \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{"title":"New Document","content":"Document body in Markdown format.","status":"draft","tags":["guide","onboarding"]}'
Response200
{ "id": "doc_03", "title": "New Document", "status": "draft", "createdAt": "2026-03-24T14:30:00Z" }

Request Body Parameters

titlestringbodyrequired

The document title. Must be between 1 and 200 characters. Displayed in navigation, search results, and browser tabs.

contentstringbody

Document body in Markdown format. Supports the full range of Markdown syntax including headings, lists, code blocks, and links.

statusstringbodyDefault: draft

Initial document status. Allowed values: draft (visible only to editors) or published (visible to all authenticated users).

tagsstring[]body

Array of tag strings for categorization. Tags are used for filtering and grouping documents in the sidebar and search results.

Update Resource

Replace an entire resource. This example uses the PUT method, which requires every field in the request body. Fields you leave out reset to their defaults.

PUThttps://api.devops.bd/api/v1/documents/:idBearer Token

Replace a document entirely. All fields are required in the request body.

Headers
AuthorizationBearer <token>
Content-Typeapplication/json
Request Body
{ "title": "Updated Document Title", "content": "Updated content.", "status": "published", "tags": [ "guide", "updated" ] }
Request Example
curl -X PUT "https://api.devops.bd/api/v1/documents/:id" \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{"title":"Updated Document Title","content":"Updated content.","status":"published","tags":["guide","updated"]}'
Response200
{ "id": "doc_03", "title": "Updated Document Title", "status": "published", "updatedAt": "2026-03-24T15:00:00Z" }
idstringpathrequired

The unique document identifier. Found in the id field of any document response object.

Partial Update

Update specific fields without replacing the whole resource. This example uses the PATCH method, which accepts a partial body. Only the fields you include change.

PATCHhttps://api.devops.bd/api/v1/documents/:idBearer Token

Update specific fields of a document without replacing the entire resource.

Headers
AuthorizationBearer <token>
Content-Typeapplication/json
Request Body
{ "status": "published" }
Request Example
curl -X PATCH "https://api.devops.bd/api/v1/documents/:id" \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{"status":"published"}'
Response200
{ "id": "doc_03", "title": "Updated Document Title", "status": "published", "updatedAt": "2026-03-24T15:30:00Z" }

Delete Resource

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

DELETEhttps://api.devops.bd/api/v1/documents/:idBearer Token

Permanently delete a document. This action cannot be undone. All associated metadata and search index entries are removed.

Headers
AuthorizationBearer <token>
Request Example
curl -X DELETE "https://api.devops.bd/api/v1/documents/:id" \ -H "Authorization: Bearer <token>"
Response200
{ "success": true, "message": "Document deleted successfully." }

Deprecated Endpoint

OwnDocs can mark endpoints as deprecated and show migration guidance. Deprecated endpoints render dimmed, with a warning that points readers to the replacement.

DeprecatedGET/api/v1/docsBearer Token
This endpoint is deprecated. Use GET /api/v1/documents instead.

Retrieve documents using the legacy endpoint.

Headers
AuthorizationBearer <token>
Request Example
curl -X GET "/api/v1/docs" \ -H "Authorization: Bearer <token>"
Response200
{ "items": [] }

Usage

To use ApiBlock in your MDX files, pass its data props as JSON strings. The component parses and formats them, then renders 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, 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 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 next to ApiBlock to document 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
Was this page helpful?