API Reference Documentation Standard

Template Overview

World-class developer platforms demand clear, accurate, and reproducible API reference documentation. The Developer Platform API Reference Standard template organizes endpoint specifications, authentication schemes, multi-language curl and SDK examples, and error taxonomy into a clean, developer-friendly Markdown format.

Markdown Template Structure

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

---
title: "API Reference: [Endpoint Group / Resource Name]"
endpoint_path: "/v2/transcripts"
http_method: "POST"
authentication: "Bearer Token (API Key / OAuth2)"
rate_limit: "1,200 requests/minute"
version: "v2.4"
tags: [api-reference, documentation, developer-platform, rest, endpoints]
---

# API Reference: Create Asynchronous Transcript

Initiates a hardware-accelerated local transcription job for an audio or video file asset.

## 1. HTTP Request Specification
`POST https://api.example.com/v2/transcripts`

### Headers
| Header Name | Type | Required | Description |
|---|---|---|---|
| `Authorization` | String | Yes | `Bearer <your_api_token>` |
| `Content-Type` | String | Yes | `application/json` |
| `X-Client-Version` | String | No | Client application version string |

### Request Body Schema
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
| `audio_file_path` | String | Yes | — | Absolute path to local audio file |
| `model_tier` | String | No | `"turbo"` | Whisper model: `"base"`, `"small"`, or `"turbo"` |
| `language` | String | No | `"auto"` | ISO 639-1 language code or `"auto"` |
| `output_format` | String | No | `"markdown"`| Format: `"markdown"`, `"json"`, or `"vtt"` |

## 2. Multi-Language Code Snippets

### cURL
```bash
curl -X POST https://api.example.com/v2/transcripts \
  -H "Authorization: Bearer sec_live_94829104" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_file_path": "/Users/user/Recordings/meeting.m4a",
    "model_tier": "turbo",
    "language": "en"
  }'

TypeScript / Node.js

import { LocalClient } from '@oyma/sdk';

const client = new LocalClient({ token: process.env.API_TOKEN });
const job = await client.transcripts.create({
  audioFilePath: '/Users/user/Recordings/meeting.m4a',
  modelTier: 'turbo',
  language: 'en',
});
console.log(`Job Created: ${job.id}`);

3. Response Codes & Error Taxonomy

Status Code	Code String	Description	Resolution Guidance
200 OK	success	Job initialized successfully	Poll job status or listen to SSE stream
400 Bad Request	invalid_parameters	Missing required parameters	Inspect request JSON payload
401 Unauthorized	unauthenticated	Missing or invalid API token	Verify token in macOS Keychain
429 Too Many Req	rate_limited	Rate limit threshold exceeded	Implement exponential backoff

## Filled Real-World Example

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

```markdown
---
title: "API Reference: Search Vault FTS5"
endpoint_path: "/v1/vault/search"
http_method: "GET"
authentication: "Local Loopback"
rate_limit: "Unlimited (Local Process)"
version: "v1.0"
tags: [api-reference, documentation, developer-platform, rest, endpoints]
---

# API Reference: Search Vault FTS5

Queries local SQLite full-text search index across all markdown documents.

## 1. Specification
`GET http://localhost:8124/v1/vault/search?q=architecture`

Returns BM25 ranked matching files in under 15 milliseconds.

When to Use and When to Avoid

When to Use

• Use when documenting REST, GraphQL, or RPC endpoints for public or internal developer platforms.
• Use to establish standardized parameter tables, header specifications, and code samples.
• Use to document HTTP response error codes and troubleshooting guidance.

When to Avoid

• Avoid for high-level marketing blog posts.
• Avoid for internal agile retrospective notes.

On-Device AI Integration

Summarize your recording in Oyma with this local instruction:

Summarize the API specification walk-through audio:
1. Extract endpoint paths, HTTP methods, headers, and parameter schemas discussed.
2. Outline request and response body examples, including error codes and rate limits.
3. List documentation tasks, sample code language needs, and authoring deadlines.
Output in clean, structured Markdown.

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