Skip to main content

API Reference

4 min readStableIntermediate

ApiBlock renders one REST endpoint as a card from a single typed operation prop: a color-coded method badge, the path, an auth indicator, request parameters and body, a cURL command built from those values, and one or more response tabs. Put ParamField and ResponseField under it when a parameter or a response key needs its own row with a type, a default, and a description. The three examples below build up from the smallest usable card to the full set of props.

Quick Start

One typed operation object with a method, a path, and a response is enough to render a card.

GET/api/health

Report whether the docs site is up.

Request Example
curl -X GET "/api/health"
Response200
{ "status": "ok" }
app/getting-started/api-reference.mdx
MDX
<ApiBlock
  operation={{
    method: 'GET',
    path: '/api/health',
    summary: 'Report whether the docs site is up.',
    responses: [{ statusCode: '200', exampleBody: '{"status":"ok"}' }],
  }}
/>

Adding Options

Add a query parameter, a request body, a 201 status, and a base URL, then describe each input and output field with ParamField and ResponseField.

POSThttps://api.example.com/api/v1/documentsBearer Token

Create a document. Only title is required; status falls back to draft.

Parameters
notifybooleanqueryDefault: false
Send a notification when the document is created.
Request Body
[ { "name": "title", "type": "string", "location": "body", "required": true }, { "name": "status", "type": "string", "location": "body", "required": false, "defaultValue": "draft" } ]
Request Example
curl -X POST "https://api.example.com/api/v1/documents?notify=false" \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{"title":"<string>","status":"draft"}'
Response201
{ "id": "doc_03", "title": "Release checklist", "status": "draft", "createdAt": "2026-03-24T14:30:00Z" }
titlestringbodyrequired

Document title, 1 to 200 characters. Shows up in navigation, search, and the browser tab.

statusstringbodyDefault: draft

Either draft or published.

idstringrequired

Server-assigned identifier. Pass it back in the path for update and delete calls.

app/getting-started/api-reference.mdx
MDX
<ApiBlock
  operation={{
    method: 'POST',
    path: '/api/v1/documents',
    summary:
      'Create a document. Only title is required; status falls back to draft.',
    parameters: [
      {
        name: 'notify',
        type: 'boolean',
        location: 'query',
        required: false,
        defaultValue: 'false',
        description: 'Send a notification when the document is created.',
      },
    ],
    requestBody: {
      fields: [
        { name: 'title', type: 'string', location: 'body', required: true },
        {
          name: 'status',
          type: 'string',
          location: 'body',
          required: false,
          defaultValue: 'draft',
        },
      ],
    },
    responses: [
      {
        statusCode: '201',
        exampleBody:
          '{"id":"doc_03","title":"Release checklist","status":"draft","createdAt":"2026-03-24T14:30:00Z"}',
      },
    ],
    auth: { scheme: 'bearer' },
  }}
  baseUrl="https://api.example.com"
/>
 
<ParamField name="title" type="string" location="body" required>
  Document title, 1 to 200 characters. Shows up in navigation, search, and the
  browser tab.
</ParamField>
 
<ParamField name="status" type="string" location="body" defaultValue="draft">
  Either `draft` or `published`.
</ParamField>
 
<ResponseField name="id" type="string" required>
  Server-assigned identifier. Pass it back in the path for update and delete
  calls.
</ResponseField>

Advanced

Two or more entries in operation.responses swap the single response for clickable status tabs, rateLimit takes a real object, operation.auth.label overrides the padlock text, and codeExamples adds tabs after the generated cURL.

POST/api/auth/verifyPassword in body

Check the site password and set a session cookie.

Rate limit: 5 requests / 15 minutes (per IP address)
Request Body
[ { "name": "password", "type": "string", "location": "body", "required": true } ]
Request Example
curl -X POST "/api/auth/verify" \ -H "Content-Type: application/json" \ -d '{"password":"<string>"}'
Response
{ "success": true }
app/getting-started/api-reference.mdx
MDX
<ApiBlock
  operation={{
    method: 'POST',
    path: '/api/auth/verify',
    summary: 'Check the site password and set a session cookie.',
    requestBody: {
      fields: [
        { name: 'password', type: 'string', location: 'body', required: true },
      ],
    },
    responses: [
      { statusCode: '200', exampleBody: '{"success":true}' },
      {
        statusCode: '401',
        label: 'Unauthorized',
        exampleBody: '{"success":false,"error":"Incorrect password."}',
      },
      {
        statusCode: '429',
        label: 'Rate Limited',
        exampleBody: '{"success":false,"error":"Too many failed attempts."}',
      },
    ],
    auth: { scheme: 'none', label: 'Password in body' },
  }}
  rateLimit={{ requests: 5, window: '15 minutes', note: 'per IP address' }}
  codeExamples={[
    {
      language: 'python',
      label: 'Python',
      code: 'import requests\n\nr = requests.post(url, json=payload)\nprint(r.status_code)',
    },
  ]}
/>

Options

ApiBlock

operationobjectrequired

The endpoint's data as one real object — a subset of the EndpointOperation type from lib/openapi-import/types.ts, so anything the OpenAPI importer produces can be passed straight through. Invalid shapes fail the build with a message naming the exact field, instead of silently rendering nothing.

operation.methodstringrequired

GET, POST, PUT, PATCH, or DELETE. Picks the badge color and the left border color: blue, green, amber, purple, red.

operation.pathstringrequired

The path shown beside the badge and used as the cURL URL.

operation.summarystring

Sentence shown under the header, above the parameters block. Falls back to operation.description when omitted.

operation.parametersarray

Array of { name, type, location, required, defaultValue, description }. Entries with location: "query" or location: "header" render as ParamField rows in a built-in Parameters section, and feed the generated cURL command's query string and -H flags.

operation.requestBodyobject

{ mediaType, example, fields }. fields pretty-prints as the Request Body panel; example (or a skeleton built from fields) becomes the cURL -d payload.

operation.responsesarray

Array of { statusCode, label, exampleBody }. Two or more render as clickable tabs; label is optional and appears next to the status code.

operation.authobject

{ scheme, label }. scheme is bearer, apiKey, basic, oauth2, or none, mapped to "Bearer Token", "API Key", "Basic Auth", "OAuth 2.0", and "No auth required". label overrides the mapped text while keeping the padlock icon. none gets an open padlock; the rest get a closed one.

operation.deprecatedbooleanDefault: false

Adds a red "Deprecated" chip to the header and fades the whole card.

operation.deprecationNotestring

Migration text shown in a red warning box above the summary.

baseUrlstring

Muted prefix before the path, also prepended to the cURL URL.

rateLimitobject

{ requests, window, note }. The object above renders as "5 requests / 15 minutes (per IP address)".

codeExamplesarray

Array of { language, label, code } items appended after the generated cURL tab. Only bash and python get real syntax highlighting; anything else falls back to the JSON grammar.

showParametersbooleanDefault: true

Set false when the page already renders operation.parameters itself (see components/OpenApiEmbed.tsx), to avoid showing the same parameters twice.

ParamField

namestringrequired

Parameter name, rendered in monospace.

typestring

Type chip, such as string, integer, or string[]. Free text, so write whatever the API actually returns.

locationstring

path, query, body, or header. Each gets its own chip color: sky, purple, teal, amber.

requiredbooleanDefault: false

Adds a red "required" label after the badges.

defaultValuestring

Rendered as Default: <value> in muted text.

deprecatedbooleanDefault: false

Strikes through the name, fades the row, and adds an amber "deprecated" label.

ResponseField

namestringrequired

Field name. Use dot paths like meta.total for nested keys.

typestring

Type chip shown next to the name.

requiredboolean

Marks the field as always present in the response.

deprecatedboolean

Same treatment as ParamField: struck-through name, faded row, amber label. There is no location prop here, since a response field has nowhere else to live.

Related pages

API Blocks

Parameter Fields

Response Fields

Was this page helpful?