Super Transcriber API Check API

REST API reference

Build transcription into your product with a small async API.

Authenticated routes accept `x-api-key: <key>` or `Authorization: Bearer <key>`. Errors use `{ "success": false, "error": "...", "code": "..." }`.

GET/health

Public uptime check with service name, version, and request id.

{
  "ok": true,
  "service": "super-transcriber-api",
  "version": "dev-local",
  "requestId": "req-123"
}
POST/v1/api-keys

Admin-only API-key creation route. Plaintext keys are returned once and stored only as SHA-256 hashes.

{
  "customerName": "Acme Dev",
  "keyName": "Production key",
  "limits": {
    "maxActiveJobs": 5,
    "maxFileSizeBytes": 209715200,
    "maxDurationSeconds": 1200,
    "monthlyTranscriptionMinutes": 120
  }
}
POST/v1/uploads/presign

Creates a private presigned S3 upload URL for MP3 or M4A files up to 200 MB.

{
  "fileName": "meeting.mp3",
  "contentType": "audio/mpeg",
  "fileSizeBytes": 1048576
}
{
  "uploadUrl": "https://...",
  "uploadMethod": "PUT",
  "jobId": "2d1d7a53-9f34-40d3-9d2a-839bfb29d821",
  "s3Key": "customers/cust_123/uploads/2d1d7a53/meeting.mp3",
  "expiresInSeconds": 900
}
POST/v1/transcriptions

Queues an asynchronous transcription job from an owned S3 key. `sourceUrl` returns `501 NOT_IMPLEMENTED` in v1.

{
  "s3Key": "customers/cust_123/uploads/job_123/meeting.mp3",
  "fileName": "meeting.mp3",
  "durationSeconds": 600,
  "speakerCount": 2
}
GET/v1/transcriptions/{jobId}

Returns job state. Complete jobs include transcript text and optional private transcript JSON URLs.

{
  "jobId": "job_123",
  "status": "COMPLETED",
  "fileName": "meeting.mp3",
  "transcriptText": "Welcome everyone..."
}
GET/v1/transcriptions?limit=20&cursor=...

Lists recent jobs for the authenticated customer with cursor pagination.

DELETE/v1/transcriptions/{jobId}

Soft deletes a job so it no longer appears in normal customer views.

POST/v1/webhooks

Configures signed completion and failure callbacks for an API-key customer.

{
  "url": "https://example.com/webhooks/super-transcriber",
  "events": ["transcription.completed", "transcription.failed"]
}
POST/v1/billing/checkout

Creates an optional Stripe Checkout session for a configured paid plan.

{
  "email": "dev@example.com",
  "planId": "starter"
}
POST/v1/billing/claim

Verifies a paid Checkout session and returns the plaintext API key once.

GET/v1/billing/account

Returns the authenticated customer's billing status and enforced limits.

POST/v1/billing/portal

Creates a Stripe Billing Portal session for subscription management.