API Documentation Endpoint Specification

Template Overview

Poor API documentation frustrates developers and leads to high support ticket volume. Developers do not want prose essays; they want exact HTTP verbs, complete path parameters, request headers, typed request bodies, and verified JSON responses. The API Documentation Endpoint Specification provides a clean CommonMark reference format for documenting developer APIs in plain Markdown.

Markdown Template Structure

Copy the block below or click Download .md File to add this template directly to your personal vault:

---
title: "API Spec: [HTTP Method] [Endpoint Path]"
date_updated: [YYYY-MM-DD]
api_version: "v1.2"
endpoint_group: "Local Vault Management"
authentication_required: false (Local IPC / Loopback)
stability_tier: "Stable / Beta / Deprecated"
tags: [api-docs, rest, developer-experience, endpoint-spec, technical-writing]
---

# API Endpoint Specification: `POST /v1/transcribe/local`

## 1. Overview & Method Summary
- **HTTP Method:** `POST`
- **Resource Path:** `/v1/transcribe/local`
- **Summary:** Transcribes an audio file on the local machine using hardware-accelerated Whisper models without network transmission.
- **Base URL:** `http://127.0.0.1:48291` (Bound exclusively to localhost loopback).

## 2. Request Headers & Authentication
| Header | Required | Type | Description |
|---|---|---|---|
| `Content-Type` | **Yes** | `application/json` | Must be `application/json` |
| `X-Client-Version` | No | `string` | Optional client telemetry identifier |

## 3. Request Body Parameters (JSON)
| Field Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `audio_path` | `string` | **Yes** | - | Absolute POSIX file path to `.wav`, `.m4a`, or `.mp3` audio file |
| `model` | `string` | No | `"small"` | Whisper model tier: `"tiny"`, `"base"`, `"small"`, `"medium"`, `"large-v3"` |
| `language` | `string` | No | `"auto"` | ISO 639-1 language code (e.g., `"en"`, `"de"`, `"fr"`) |
| `temperature` | `number` | No | `0.0` | Sampling temperature between `0.0` and `1.0` |

### Sample Request Payload:
```json
{
  "audio_path": "/Users/developer/Audio/design_sync_2026.m4a",
  "model": "small",
  "language": "en",
  "temperature": 0.0
}

4. Response Schemas & Status Codes

HTTP 200 OK (Success)

Returned when audio transcription completes successfully.

{
  "status": "success",
  "duration_seconds": 184.2,
  "processing_time_ms": 3410,
  "model_used": "small.en",
  "segments": [
    {
      "id": 0,
      "start": 0.0,
      "end": 4.5,
      "text": "Good morning everyone, let's review the architectural decision record."
    },
    {
      "id": 1,
      "start": 4.8,
      "end": 9.2,
      "text": "We are evaluating local-first SQLite indexes versus flat Markdown parsing."
    }
  ],
  "full_transcript": "Good morning everyone, let's review the architectural decision record. We are evaluating local-first SQLite indexes versus flat Markdown parsing."
}

HTTP 400 Bad Request

Returned when input parameters are invalid or file does not exist.

{
  "error": "invalid_audio_path",
  "message": "Specified audio file does not exist or lacks read permissions.",
  "code": 4001
}

5. Developer Code Samples

cURL Request:

curl -X POST http://127.0.0.1:48291/v1/transcribe/local \
  -H "Content-Type: application/json" \
  -d '{
    "audio_path": "/Users/developer/Audio/sync.m4a",
    "model": "small"
  }'

Python Request:

import requests

response = requests.post(
    "http://127.0.0.1:48291/v1/transcribe/local",
    json={"audio_path": "/Users/developer/Audio/sync.m4a", "model": "small"}
)
transcript = response.json()["full_transcript"]
print(f"Transcript: {transcript}")

6. Implementation Notes & Limitations

[!NOTE] Performance Tip Audio files longer than 2 hours should be provided in 16kHz mono 16-bit PCM .wav format to minimize in-memory audio transcoding overhead.

## Filled Real-World Example

Here is a realistic example demonstrating how this template captures actual deliberations:

```markdown
---
title: "API Spec: GET /v1/vault/notes"
date_updated: 2026-10-07
api_version: "v1.0"
endpoint_group: "Notes"
stability_tier: "Stable"
tags: [api-docs, rest]
---

# API Endpoint Specification: `GET /v1/vault/notes`

## 1. Summary
Returns all indexed Markdown notes within the currently active vault directory with frontmatter metadata.

## 2. Sample Response
```json
{
  "notes_count": 240,
  "vault_path": "/Users/user/Documents/KnowledgeVault",
  "last_indexed": "2026-10-07T12:00:00Z"
}

## When to Use and When to Avoid

### When to Use
- Use when writing developer documentation for public or internal REST/RPC APIs.
- Use to create clear contracts between frontend and backend engineering teams.
- Use to generate automated documentation websites using static site generators.

### When to Avoid
- Avoid using for conceptual narrative essays or marketing press releases.
- Avoid omitting parameter types, defaults, or realistic JSON response examples.

## On-Device AI Integration

Summarize your recording in Oyma with this local instruction:

```markdown
Analyze the backend route handler code or OpenAPI schema:
1. Extract HTTP method, route path, headers, query parameters, and JSON body fields.
2. Generate comprehensive success (200) and error (400, 500) JSON response schemas.
3. Formulate an idiomatic API documentation endpoint specification with cURL and Python samples in Markdown.

Your data remains securely on your Mac with zero cloud exposure.