TranscribeHQ API

Returns the server health status. No authentication required.

Response 200

{
  "status": "ok"
}

Example

# curl
curl https://your-domain/api/healthz

Submit a video URL to start the transcription pipeline. Optionally provide a webhook URL to receive a notification when processing completes.

Request Body

Request Example

curl -X POST https://your-domain/api/v1/transcribe \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "webhook_url": "https://your-server.com/webhook"
  }'

Response 202

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "platform": "YouTube",
  "tier": 1,
  "warning": null,
  "poll_url": "/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000"
}

Error Responses

Returns a summary list of all transcription jobs.

Response 200

{
  "jobs": [
    {
      "job_id": "550e8400-...",
      "url": "https://www.youtube.com/watch?v=...",
      "platform": "YouTube",
      "status": "complete",
      "progress": 100,
      "is_loom": false,
      "created_at": "2026-03-13T01:00:00.000Z"
    }
  ],
  "total": 1
}

Example

curl https://your-domain/api/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns the full job status and results. The response includes transcripts, quality scores, corrections, cleaned transcripts, task briefs, and visual context annotations.

Path Parameters

Response 200 — Complete Job

{
  "job_id": "550e8400-...",
  "status": "complete",
  "platform": "Loom",
  "is_loom": true,
  "progress": 100,
  "raw_transcript": "So today I want to show you...",
  "corrected_transcript": "So today I want to show you...",
  "cleaned_transcript": "Today I want to show you...",
  "quality_score": 88,
  "corrections": [
    {
      "timestamp": "00:01:23",
      "original": "their",
      "issue": "Homophone error",
      "suggested_correction": "there",
      "confidence": "high"
    }
  ],
  "brief": {
    "summary": "Client requests changes to...",
    "platforms": ["WordPress", "Elementor"],
    "task_type": "Update",
    "priority": "Normal",
    "requirements": ["1. Update hero section..."],
    "ambiguities": ["Which color scheme?"],
    "suggested_hero": "Web Hero",
    "hero_reasoning": "WordPress/Elementor task"
  },
  "visual_context": {
    "confirmed_annotations": [
      {
        "timestamp": "00:00:42",
        "trigger_phrase": "this button right here",
        "platform": "WordPress",
        "ui_element": "CTA button in hero section",
        "context": "Elementor editor showing hero block",
        "visible_text": "Get Started Now",
        "confidence": "high"
      }
    ],
    "unverified_annotations": [],
    "platform_summary": { "WordPress": 2 },
    "total_confirmed": 2,
    "total_dismissed": 1
  },
  "activity_log": [
    {
      "step": "transcription",
      "label": "Deepgram Transcription",
      "status": "complete",
      "elapsed": 3.2
    }
  ],
  "error": null
}

Job Status Values