### Initialize and Start Application

Source: https://github.com/deepgram-starters/go-transcription/blob/main/AGENTS.md

Commands to initialize submodules, install dependencies, and start the backend and frontend servers.

```bash
# Initialize (clone submodules + install deps)
make init

# Set up environment
test -f .env || cp sample.env .env  # then set DEEPGRAM_API_KEY

# Start both servers
make start
# Backend: http://localhost:8081
# Frontend: http://localhost:8080
```

--------------------------------

### Initialize and Start the Go Application

Source: https://github.com/deepgram-starters/go-transcription/blob/main/README.md

Use the Makefile to initialize the environment, configure the API key, and start the local server.

```bash
make init
cp sample.env .env  # Add your DEEPGRAM_API_KEY
make start
```

--------------------------------

### Install Dependencies

Source: https://github.com/deepgram-starters/go-transcription/blob/main/AGENTS.md

Commands to manually install backend Go modules and frontend dependencies.

```bash
go mod download
Frontend: cd frontend && corepack pnpm install
```

--------------------------------

### Transcription Parameter Setup

Source: https://context7.com/deepgram-starters/go-transcription/llms.txt

Example of setting the token variable for use with transcription parameters.

```bash
TOKEN=$(curl -s http://localhost:8081/api/session | jq -r '.token')
```

--------------------------------

### Initialize and Start the Project

Source: https://context7.com/deepgram-starters/go-transcription/llms.txt

Commands to clone the repository, configure the environment variables, and launch the development servers.

```bash
# Clone and initialize the project
git clone https://github.com/deepgram-starters/go-transcription.git
cd go-transcription
make init

# Configure your API key
cp sample.env .env
# Edit .env and set DEEPGRAM_API_KEY=your_api_key_here

# Start both backend and frontend
make start

# Application will be available at:
# Frontend: http://localhost:8080
# Backend API: http://localhost:8081
```

--------------------------------

### Start and Stop Commands

Source: https://github.com/deepgram-starters/go-transcription/blob/main/AGENTS.md

Commands for managing the application lifecycle, including starting components separately, stopping all processes, and performing clean rebuilds.

```bash
make start
```

```bash
# Terminal 1 — Backend
go run .

# Terminal 2 — Frontend
cd frontend && corepack pnpm run dev -- --port 8080 --no-open
```

```bash
lsof -ti:8080,8081 | xargs kill -9 2>/dev/null
```

```bash
rm -rf frontend/node_modules frontend/.vite
make init
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/deepgram-starters/go-transcription/blob/main/AGENTS.md

Standardized commit message formats for the project.

```text
feat(go-transcription): add diarization support
fix(go-transcription): resolve WebSocket close handling
refactor(go-transcription): simplify session endpoint
chore(deps): update frontend submodule
```

--------------------------------

### Makefile Commands for Development

Source: https://context7.com/deepgram-starters/go-transcription/llms.txt

A collection of Makefile commands for managing the Go Transcription project. These commands cover initialization, starting the application, testing, and cleaning build artifacts.

```bash
# Show all available commands
make help

# Check prerequisites (git, go, pnpm)
make check-prereqs

# Initialize project (clone submodules, install dependencies)
make init

# Start application (backend + frontend)
make start

# Start only backend (port 8081)
make start-backend

# Start only frontend (port 8080)
make start-frontend

# Run contract conformance tests
make test

# Update git submodules to latest
make update

# Clean build artifacts and dependencies
make clean

# Show git and submodule status
make status

# Eject frontend from submodule to regular directory
make eject-frontend
```

--------------------------------

### Error Handling Examples (cURL)

Source: https://context7.com/deepgram-starters/go-transcription/llms.txt

Demonstrates how to handle common API errors such as missing authorization tokens, invalid tokens, and missing input parameters. The responses show structured error objects.

```bash
TOKEN=$(curl -s http://localhost:8081/api/session | jq -r '.token')

# Missing authorization token (401)
curl -X POST http://localhost:8081/api/transcription \
  -F "url=https://example.com/audio.mp3"
# Response:
{
  "error": {
    "type": "AuthenticationError",
    "code": "MISSING_TOKEN",
    "message": "Authorization header with Bearer token is required"
  }
}

# Invalid/expired token (401)
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer invalid_token" \
  -F "url=https://example.com/audio.mp3"
# Response:
{
  "error": {
    "type": "AuthenticationError",
    "code": "INVALID_TOKEN",
    "message": "Invalid session token"
  }
}

# Missing input (400)
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN"
# Response:
{
  "error": {
    "type": "ValidationError",
    "code": "MISSING_INPUT",
    "message": "Either file or url must be provided"
  }
}
```

--------------------------------

### Transcribe Audio Files and URLs

Source: https://context7.com/deepgram-starters/go-transcription/llms.txt

Examples for sending audio files or URLs to the transcription endpoint with various configuration parameters.

```bash
# Transcribe an uploaded audio file
TOKEN=$(curl -s http://localhost:8081/api/session | jq -r '.token')

curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/audio.mp3" \
  -F "model=nova-3" \
  -F "language=en" \
  -F "smart_format=true" \
  -F "punctuate=true"

# Transcribe audio from a URL
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "url=https://static.deepgram.com/examples/Bueller-Life-moves-702.mp3" \
  -F "model=nova-3" \
  -F "diarize=true" \
  -F "paragraphs=true"

# Response:
{
  "transcript": "Life moves pretty fast. If you don't stop and look around once in a while, you could miss it.",
  "words": [
    {"word": "life", "start": 0.08, "end": 0.32, "confidence": 0.99},
    {"word": "moves", "start": 0.32, "end": 0.56, "confidence": 0.98}
  ],
  "metadata": {
    "model_name": "nova-3",
    "model_uuid": "...",
    "request_id": "..."
  },
  "duration": 4.07
}

# With additional features enabled
curl -X POST "http://localhost:8081/api/transcription?model=nova-3&diarize=true&utterances=true&filler_words=true" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@interview.wav"
```

--------------------------------

### Docker Deployment Commands

Source: https://context7.com/deepgram-starters/go-transcription/llms.txt

Build and run the Go Transcription application as a Docker container. This includes instructions for building the image, running the container, and accessing the application.

```bash
# Build the Docker image
docker build -f deploy/Dockerfile -t go-transcription .

# Run the container
docker run -d \
  --name go-transcription \
  -p 8080:8080 \
  -e DEEPGRAM_API_KEY=your_api_key_here \
  -e SESSION_SECRET=your_secure_secret \
  go-transcription

# Access the application at http://localhost:8080
# All API endpoints are proxied through Caddy with rate limiting:
# - /api/session: 5 requests/minute per IP
# - /api/*: 120 requests/minute per IP

# Health check
curl http://localhost:8080/health
```

--------------------------------

### Run Tests and Endpoint Checks

Source: https://github.com/deepgram-starters/go-transcription/blob/main/AGENTS.md

Commands to execute conformance tests and verify API endpoints.

```bash
# Run conformance tests (requires app to be running)
make test

# Manual endpoint check
curl -sf http://localhost:8081/api/metadata | python3 -m json.tool
curl -sf http://localhost:8081/api/session | python3 -m json.tool
```

--------------------------------

### Fly.io Deployment Commands

Source: https://context7.com/deepgram-starters/go-transcription/llms.txt

Deploy the Go Transcription application to Fly.io using the provided fly.toml configuration. This includes setting up secrets and deploying the application.

```bash
# Install Fly CLI and authenticate
curl -L https://fly.io/install.sh | sh
fly auth login

# Create the app (first time only)
fly launch --no-deploy

# Set your Deepgram API key as a secret
fly secrets set DEEPGRAM_API_KEY=your_api_key_here
fly secrets set SESSION_SECRET=$(openssl rand -hex 32)

# Deploy the application
fly deploy

# View logs
fly logs

# Open in browser
fly open
```

--------------------------------

### Retrieve Application Metadata

Source: https://context7.com/deepgram-starters/go-transcription/llms.txt

Fetches configuration details from the deepgram.toml file.

```bash
curl -X GET http://localhost:8081/api/metadata

# Response:
{
  "title": "Go Transcription",
  "description": "Get started using Deepgram's speech-to-text with this Go demo app",
  "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
  "repository": "https://github.com/deepgram-starters/go-transcription",
  "useCase": "transcription",
  "language": "go",
  "framework": "go",
  "tags": ["speech-to-text", "transcription", "prerecorded", "go"]
}
```

--------------------------------

### Manage Frontend Submodule

Source: https://github.com/deepgram-starters/go-transcription/blob/main/AGENTS.md

Commands to update and commit changes to the frontend git submodule.

```bash
cd frontend && git add . && git commit -m "feat: description"
```

```bash
cd frontend && git push origin main
```

```bash
cd .. && git add frontend && git commit -m "chore(deps): update frontend submodule"
```

--------------------------------

### Environment Variables Configuration (.env file)

Source: https://context7.com/deepgram-starters/go-transcription/llms.txt

Configure the Deepgram Go Transcription application using environment variables. Copy the sample.env file and customize your Deepgram API key and other settings.

```bash
# .env file configuration
# Required - Your Deepgram API key from https://console.deepgram.com
DEEPGRAM_API_KEY=your_api_key_here

# Optional - Backend server port (default: 8081)
PORT=8081

# Optional - Server bind address (default: 0.0.0.0)
HOST=0.0.0.0

# Optional - JWT signing secret for production (auto-generated if not set)
SESSION_SECRET=your_secure_random_string

# Verify configuration
source .env
echo "API Key set: ${DEEPGRAM_API_KEY:+yes}"
```

--------------------------------

### Spanish Transcription with Diarization (cURL)

Source: https://context7.com/deepgram-starters/go-transcription/llms.txt

This command transcribes a Spanish audio file from a URL, enabling speaker diarization and smart formatting. Replace the URL with your audio source.

```bash
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "url=https://example.com/spanish-meeting.mp3" \
  -F "model=nova-3" \
  -F "language=es" \
  -F "diarize=true" \
  -F "smart_format=true"
```

--------------------------------

### Transcribe Audio with Various Parameters (cURL)

Source: https://context7.com/deepgram-starters/go-transcription/llms.txt

Use this command to transcribe an audio file with multiple Deepgram API parameters. Ensure you have a valid token and audio file.

```bash
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@audio.mp3" \
  -F "model=nova-3" \
  -F "language=en" \
  -F "smart_format=true" \
  -F "diarize=true" \
  -F "punctuate=true" \
  -F "paragraphs=true" \
  -F "utterances=true" \
  -F "filler_words=true"
```

--------------------------------

### Application Metadata API

Source: https://context7.com/deepgram-starters/go-transcription/llms.txt

Returns application metadata from the deepgram.toml configuration file.

```APIDOC
## GET /api/metadata

### Description
Returns application metadata from the `deepgram.toml` configuration file, including use case, framework, language, and tags. This endpoint is unprotected.

### Method
GET

### Endpoint
/api/metadata

### Response
#### Success Response (200)
- **title** (string) - The title of the application.
- **description** (string) - A description of the application.
- **author** (string) - The author of the application.
- **repository** (string) - The URL of the application's repository.
- **useCase** (string) - The primary use case of the application.
- **language** (string) - The programming language used.
- **framework** (string) - The framework used.
- **tags** (array of strings) - Tags associated with the application.

#### Response Example
```json
{
  "title": "Go Transcription",
  "description": "Get started using Deepgram's speech-to-text with this Go demo app",
  "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
  "repository": "https://github.com/deepgram-starters/go-transcription",
  "useCase": "transcription",
  "language": "go",
  "framework": "go",
  "tags": ["speech-to-text", "transcription", "prerecorded", "go"]
}
```
```

--------------------------------

### Health Check Endpoint

Source: https://context7.com/deepgram-starters/go-transcription/llms.txt

Verifies the backend service status for monitoring and orchestration.

```bash
curl -X GET http://localhost:8081/health

# Response:
{
  "status": "ok"
}

# Use in Docker health checks or Kubernetes probes
# Docker: HEALTHCHECK CMD curl -f http://localhost:8081/health || exit 1
# Kubernetes: livenessProbe: httpGet: path: /health port: 8081
```

--------------------------------

### Request a Session Token

Source: https://context7.com/deepgram-starters/go-transcription/llms.txt

Retrieves a signed JWT token required for authenticating with protected API endpoints.

```bash
# Request a new session token
curl -X GET http://localhost:8081/api/session

# Response:
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MDk1MTQwMDAsImV4cCI6MTcwOTUxNzYwMH0.abc123..."
}

# Store the token for subsequent requests
TOKEN=$(curl -s http://localhost:8081/api/session | jq -r '.token')
echo "Session token: $TOKEN"
```

--------------------------------

### User Authentication API

Source: https://context7.com/deepgram-starters/go-transcription/llms.txt

Issues a signed JWT token for authenticating subsequent API requests. The token expires after 1 hour and must be included in the Authorization header for protected endpoints.

```APIDOC
## GET /api/session

### Description
Issues a signed JWT token for authenticating subsequent API requests. The token expires after 1 hour and must be included in the Authorization header for protected endpoints like `/api/transcription`.

### Method
GET

### Endpoint
/api/session

### Request Example
```bash
curl -X GET http://localhost:8081/api/session
```

### Response
#### Success Response (200)
- **token** (string) - The JWT session token.

#### Response Example
```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MDk1MTQwMDAsImV4cCI6MTcwOTUxNzYwMH0.abc123..."
}
```
```

--------------------------------

### Health Check API

Source: https://context7.com/deepgram-starters/go-transcription/llms.txt

A simple health check endpoint for container orchestration and monitoring.

```APIDOC
## GET /health

### Description
Simple health check endpoint for container orchestration and monitoring. Returns a status indicator to verify the backend is running and responsive.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - Indicates the health status, typically "ok".

#### Response Example
```json
{
  "status": "ok"
}
```

### Usage Examples
```bash
# Use in Docker health checks or Kubernetes probes
# Docker: HEALTHCHECK CMD curl -f http://localhost:8081/health || exit 1
# Kubernetes: livenessProbe: httpGet: path: /health port: 8081
```
```

--------------------------------

### Audio Transcription API

Source: https://context7.com/deepgram-starters/go-transcription/llms.txt

Transcribes audio files using Deepgram's pre-recorded speech-to-text API. Accepts either file uploads via multipart/form-data or audio URLs. Requires JWT authentication.

```APIDOC
## POST /api/transcription

### Description
Transcribes audio files using Deepgram's pre-recorded speech-to-text API. Accepts either file uploads via multipart/form-data or audio URLs. Requires JWT authentication via the Authorization header. Supports configurable models and various transcription features.

### Method
POST

### Endpoint
/api/transcription

### Parameters
#### Query Parameters
- **model** (string) - Optional - The transcription model to use (e.g., nova-3, nova-2, base).
- **language** (string) - Optional - The language of the audio.
- **smart_format** (boolean) - Optional - Enables smart formatting.
- **punctuate** (boolean) - Optional - Enables punctuation.
- **diarize** (boolean) - Optional - Enables speaker diarization.
- **paragraphs** (boolean) - Optional - Enables paragraph detection.
- **utterances** (boolean) - Optional - Enables utterance detection.
- **filler_words** (boolean) - Optional - Enables filler word detection.

#### Request Body
- **file** (file) - Optional - The audio file to transcribe (multipart/form-data).
- **url** (string) - Optional - The URL of the audio file to transcribe.

### Request Example
```bash
# Transcribe an uploaded audio file
TOKEN=$(curl -s http://localhost:8081/api/session | jq -r '.token')

curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/audio.mp3" \
  -F "model=nova-3" \
  -F "language=en" \
  -F "smart_format=true" \
  -F "punctuate=true"

# Transcribe audio from a URL
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "url=https://static.deepgram.com/examples/Bueller-Life-moves-702.mp3" \
  -F "model=nova-3" \
  -F "diarize=true" \
  -F "paragraphs=true"

# With additional features enabled via query parameters
curl -X POST "http://localhost:8081/api/transcription?model=nova-3&diarize=true&utterances=true&filler_words=true" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@interview.wav"
```

### Response
#### Success Response (200)
- **transcript** (string) - The transcribed text.
- **words** (array) - An array of word objects, each with `word`, `start`, `end`, and `confidence`.
- **metadata** (object) - Metadata about the transcription request.
  - **model_name** (string) - The name of the model used.
  - **model_uuid** (string) - The UUID of the model used.
  - **request_id** (string) - The ID of the transcription request.
- **duration** (number) - The duration of the audio in seconds.

#### Response Example
```json
{
  "transcript": "Life moves pretty fast. If you don't stop and look around once in a while, you could miss it.",
  "words": [
    {"word": "life", "start": 0.08, "end": 0.32, "confidence": 0.99},
    {"word": "moves", "start": 0.32, "end": 0.56, "confidence": 0.98}
  ],
  "metadata": {
    "model_name": "nova-3",
    "model_uuid": "...",
    "request_id": "..."
  },
  "duration": 4.07
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.