API documentation

Transcribe and wait for the result

Submit a source and receive the finished transcript in the SAME response — no job id, no polling loop. Returns **200** with `transcript` (and `segments`) once the transcription completes, which is immediate when the source is already in the shared cache. Long audio does not fit in one HTTP request. When the transcription is still running after the wait window (default 30s, `?wait=` up to 120s), the response is **202** with the job `id` and `status: "processing"` — the job keeps running, and GET /transcriptions/{id} retrieves it exactly as with the asynchronous API. Treat 202 as "not finished yet", never as a failure. A job that fails within the window returns **200** with `status: "failed"` and `error` set: the request succeeded, the transcription did not.

curl -X POST https://api.techtuel.com/v1/transcribe \
  -H "Authorization: Bearer txl_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/episode.mp3",
    "preferred_language": "fr",
    "source_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "upload_id": "up_abc123"
  }'

{
  "api_key_id": "key_abc123",
  "created_at": "2026-07-21T09:30:00Z",
  "detected_language": "it",
  "error": "string",
  "id": "job_abc123",
  "language": "fr",
  "minutes": 12.5,
  "segments": [
    {
      "start_seconds": 12.5,
      "text": "Bonjour et bienvenue dans cet"
    }
  ],
  "source_kind": "url",
  "source_url": "https://youtu.be/dQw4w9WgXcQ",
  "status": "processing",
  "title": "Le 6-9 de France Inter",
  "transcript": "string",
  "translated": true
}

400

Bad Request

401

Unauthorized

402

Refused: `reason` says which — `quota_exceeded` or `payment_failed`

Transcribe a local file in one call

Send the audio/video file itself and receive the finished transcript in the SAME response — no upload slot, no polling loop. This is the one-call form of the three-step upload flow (POST /uploads → PUT → POST /transcribe). Send `multipart/form-data` with the bytes in a `file` part; `Content-Type` of that part decides the accepted format. Limited to 100 MiB per request, well below what POST /uploads accepts (200 MiB audio, 1 GiB video): here the bytes travel through the API, whereas a presigned upload goes straight to storage. A larger file gets **413** naming the presigned flow — use it, it is not a downgrade but the shape that works for big files. Wait semantics are identical to POST /transcribe: **200** once the transcription completes, **202** with the job `id` when it is still running after the wait window (default 30s, `?wait=` up to 120s). Upload time counts against that window, so a large file is likelier to answer 202 — the job keeps running and GET /transcriptions/{id} retrieves it.

curl -X POST https://api.techtuel.com/v1/transcribe/file \
  -H "Authorization: Bearer txl_your_api_key" \
  -F file=@/path/to/episode.mp3 \
  -F preferred_language=fr

{
  "api_key_id": "key_abc123",
  "created_at": "2026-07-21T09:30:00Z",
  "detected_language": "it",
  "error": "string",
  "id": "job_abc123",
  "language": "fr",
  "minutes": 12.5,
  "segments": [
    {
      "start_seconds": 12.5,
      "text": "Bonjour et bienvenue dans cet"
    }
  ],
  "source_kind": "url",
  "source_url": "https://youtu.be/dQw4w9WgXcQ",
  "status": "processing",
  "title": "Le 6-9 de France Inter",
  "transcript": "string",
  "translated": true
}

400

Missing file part or unsupported format

401

Unauthorized

402

Refused: `reason` says which — `quota_exceeded` or `payment_failed`

413

File exceeds the inline limit — use POST /uploads

503

Uploads not configured

List transcription jobs

Return the authenticated owner's transcription jobs, newest first, one page at a time. Use ?page= (1-based) and ?per_page= (default 20, max 100); the response carries `total` and `has_more` so a client can append the next page. Rows do NOT include the joined transcript — only `preview_segments` (the first few timed segments) and `has_transcript`. Fetch GET /transcriptions/{id} for the full text of a single job. Pass ?api_key_id= to list only jobs submitted by that API key (jobs created from the web console are excluded).

curl -X GET https://api.techtuel.com/v1/transcriptions \
  -H "Authorization: Bearer txl_your_api_key"

{
  "has_more": true,
  "jobs": [
    {
      "api_key_id": "key_abc123",
      "created_at": "2026-07-21T09:30:00Z",
      "error": "string",
      "has_transcript": true,
      "id": "job_abc123",
      "minutes": 12.5,
      "preview_segments": [],
      "source_kind": "url",
      "source_url": "https://youtu.be/dQw4w9WgXcQ",
      "status": "processing",
      "title": "Le 6-9 de France Inter"
    }
  ],
  "page": 1,
  "per_page": 10,
  "total": 47
}

401

Unauthorized

Create a transcription job

Submit a source for transcription. Returns immediately with a job; poll GET /transcriptions/{id} until `status` is `completed` or `failed`. Prefer POST /transcribe when you just want the text: it returns the finished transcript in one request and needs no polling loop. `status` is one of `processing`, `claimed` (a worker took the job), `completed` or `failed`. Only the last two are terminal — stop polling on either. A cached or already-submitted source comes back `completed` right away, with the transcript in the same response.

curl -X POST https://api.techtuel.com/v1/transcriptions \
  -H "Authorization: Bearer txl_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "preferred_language": "fr"
  }'

{
  "api_key_id": "key_abc123",
  "created_at": "2026-07-21T09:30:00Z",
  "detected_language": "it",
  "error": "string",
  "id": "job_abc123",
  "language": "fr",
  "minutes": 12.5,
  "segments": [
    {
      "start_seconds": 12.5,
      "text": "Bonjour et bienvenue dans cet"
    }
  ],
  "source_kind": "url",
  "source_url": "https://youtu.be/dQw4w9WgXcQ",
  "status": "processing",
  "title": "Le 6-9 de France Inter",
  "transcript": "string",
  "translated": true
}

400

Bad Request

401

Unauthorized

402

Refused: `reason` says which — `quota_exceeded` (the period's allowance is spent; it refills on renewal) or `payment_failed` (the subscription is unpaid; update the payment method)

Get a transcription job

Fetch a transcription job by id. The default response is the JSON job envelope (status + joined text). Pass ?format= to download the transcript in a timed format once the job is completed: `txt` (plain text), `json` (text + timed segments), `srt` (SubRip subtitles), `vtt` (WebVTT subtitles).

curl -X GET https://api.techtuel.com/v1/transcriptions/job_abc123 \
  -H "Authorization: Bearer txl_your_api_key"

{
  "api_key_id": "key_abc123",
  "created_at": "2026-07-21T09:30:00Z",
  "detected_language": "it",
  "error": "string",
  "id": "job_abc123",
  "language": "fr",
  "minutes": 12.5,
  "segments": [
    {
      "start_seconds": 12.5,
      "text": "Bonjour et bienvenue dans cet"
    }
  ],
  "source_kind": "url",
  "source_url": "https://youtu.be/dQw4w9WgXcQ",
  "status": "processing",
  "title": "Le 6-9 de France Inter",
  "transcript": "string",
  "translated": true
}

401

Unauthorized

404

Not Found

409

Conflict

422

Unprocessable Entity

Delete a transcription

Removes a finished (completed or failed) transcription from the caller's history. The transcript itself stays in the shared source cache, so re-submitting the same source later is still served without re-transcribing. A job still in flight cannot be deleted; wait for it to finish.

curl -X DELETE https://api.techtuel.com/v1/transcriptions/job_abc123 \
  -H "Authorization: Bearer txl_your_api_key"

"string"

404

Not Found

Retry a failed transcription

Re-queues a failed transcription on the SAME job, so the history keeps one row per source instead of accumulating one per attempt. Only failed jobs can be retried, and the retry is subject to the monthly quota.

curl -X POST https://api.techtuel.com/v1/transcriptions/job_abc123/retry \
  -H "Authorization: Bearer txl_your_api_key"

{
  "api_key_id": "key_abc123",
  "created_at": "2026-07-21T09:30:00Z",
  "detected_language": "it",
  "error": "string",
  "id": "job_abc123",
  "language": "fr",
  "minutes": 12.5,
  "segments": [
    {
      "start_seconds": 12.5,
      "text": "Bonjour et bienvenue dans cet"
    }
  ],
  "source_kind": "url",
  "source_url": "https://youtu.be/dQw4w9WgXcQ",
  "status": "processing",
  "title": "Le 6-9 de France Inter",
  "transcript": "string",
  "translated": true
}

402

Refused: `reason` is `quota_exceeded` or `payment_failed`

404

Not Found

Extract clean, structured text from a web page

Fetches a public web page, strips navigation/ads/boilerplate, and returns its title, metadata and readable text — both flattened and split into positioned segments. Synchronous: no job id, no polling. Costs 1 credit; a page already in the global cache is free.

curl -X POST https://api.techtuel.com/v1/v1/extract \
  -H "Authorization: Bearer txl_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article"
  }'

{
  "author": "string",
  "cached": false,
  "charCount": 0,
  "creditsCharged": 0,
  "description": "string",
  "extractedAt": "string",
  "imageUrl": "string",
  "segments": [
    {
      "charLength": 0,
      "charOffset": 0,
      "sectionTitle": "string",
      "text": "string"
    }
  ],
  "siteName": "string",
  "sourceId": "string",
  "sourceType": "webpage",
  "text": "string",
  "title": "string",
  "url": "string"
}

400

invalid or disallowed url

402

monthly credit allowance exhausted

404

page not found

422

page yielded no readable content (paywall, JS-only app, or no prose)

502

page could not be fetched

503

site is rate limiting us; retry later

Create a file upload slot

Returns a presigned PUT URL. Upload the audio/video file directly to put_url with exactly the declared size_bytes, then POST /transcriptions with the returned upload_id. content_type and size_bytes are signed into the URL: the store rejects an upload that does not match. Size limits depend on the medium: 200 MiB for audio (the full 2h at up to 232 kbit/s), 1 GiB for video (about 30 min of 1080p at 4 Mbit/s). Longer video does not fit an upload — submit it by URL, where only the 2h duration cap applies. The URL is valid for 30 minutes.

curl -X POST https://api.techtuel.com/v1/uploads \
  -H "Authorization: Bearer txl_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content_type": "audio/mpeg",
    "filename": "episode.mp3",
    "size_bytes": 18400000
  }'

{
  "expires_at": "2026-06-04T12:15:00Z",
  "put_url": "https://s3.fr-par.scw.cloud/...",
  "upload_id": "up_abc123"
}

400

Missing/unsupported content_type or size_bytes

401

Unauthorized

413

File exceeds the size limit

503

Uploads not configured

List API keys

List the authenticated user's API keys. The token hash and raw secret are never returned — only metadata (id, name, prefix, last 4 chars, timestamps).

curl -X GET https://api.techtuel.com/v1/keys \
  -H "Authorization: Bearer txl_your_api_key"

{
  "keys": [
    {
      "created_at": "2026-06-05T10:00:00Z",
      "id": "key_abc123",
      "last4": "a1b2",
      "last_used_at": "2026-06-05T12:30:00Z",
      "name": "production server",
      "prefix": "txl_"
    }
  ]
}

401

Unauthorized

Create an API key

Mint a new API key for the authenticated user. The raw token is returned exactly once in the `token` field — store it now, it can never be retrieved again. Only available to a logged-in web session (an API key cannot mint another key).

curl -X POST https://api.techtuel.com/v1/keys \
  -H "Authorization: Bearer txl_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production server"
  }'

{
  "created_at": "2026-06-05T10:00:00Z",
  "id": "key_abc123",
  "last4": "a1b2",
  "last_used_at": "2026-06-05T12:30:00Z",
  "name": "production server",
  "prefix": "txl_",
  "token": "txl_a1b2c3d4e5f6..."
}

400

Bad Request

401

Unauthorized

403

Authenticated with an API key, not a session

Revoke an API key

Permanently revoke one of the authenticated user's API keys. Idempotent: revoking an unknown or already-revoked key still returns 204. Only available to a logged-in web session.

curl -X DELETE https://api.techtuel.com/v1/keys/key_abc123 \
  -H "Authorization: Bearer txl_your_api_key"

401

Unauthorized

403

Authenticated with an API key, not a session

Start a subscription / credit checkout

Returns a hosted-checkout URL for the requested plan. Redirect the user there to subscribe or buy credits.

curl -X POST https://api.techtuel.com/v1/billing/checkout \
  -H "Authorization: Bearer txl_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "name": "Ada Lovelace",
    "plan": "pro",
    "success_url": "https://app.example.com/billing/return"
  }'

{
  "checkout_url": "string"
}

400

Bad Request

401

Unauthorized

409

Already subscribed

503

Billing not configured

List the pricing tiers

Returns the public plans (Free, Pro, Max) with their monthly allocations and price, for the pricing page and the upgrade choice. A plan is only checkoutable when purchasable is true. No auth required.

curl -X GET https://api.techtuel.com/v1/billing/plans \
  -H "Authorization: Bearer txl_your_api_key"

{
  "plans": [
    {
      "credits": 2000,
      "currency": "EUR",
      "name": "pro",
      "price_cents": 900,
      "purchasable": true,
      "rate_per_min": 120
    }
  ]
}

Cancel your subscription

Stops future charges. Access continues until the end of the period already paid — the month is not refunded and not revoked. Idempotent: cancelling with no subscription succeeds.

curl -X DELETE https://api.techtuel.com/v1/billing/subscription \
  -H "Authorization: Bearer txl_your_api_key"

{
  "access_until": "2026-08-24T09:00:00Z",
  "active": true,
  "status": "canceled"
}

401

Unauthorized

502

Payment provider refused the cancellation

503

Billing not configured

Move your subscription to another tier

Changes the tier of an active subscription. The new allowance applies immediately; the new price applies from the next renewal — the month already paid is neither re-charged nor refunded. Refused when the subscription is unpaid or cancelled.

curl -X POST https://api.techtuel.com/v1/billing/upgrade \
  -H "Authorization: Bearer txl_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "max"
  }'

{
  "allowance_from": "now",
  "charged_from": "2026-08-24T09:00:00Z",
  "plan": "max"
}

400

Unknown or unsellable plan, or nothing to upgrade

401

Unauthorized

409

Subscription cannot be upgraded (unpaid or cancelled)

503

Billing not configured

Get transcription usage / entitlement

Returns the caller's subscription status and monthly transcription consumption.

curl -X GET https://api.techtuel.com/v1/usage \
  -H "Authorization: Bearer txl_your_api_key"

{
  "access_ends_at": "2026-08-03T00:00:00Z",
  "active": true,
  "billing_state": "healthy",
  "credits_limit": 2000,
  "credits_used": 84,
  "plan": "pro",
  "rate_per_min": 120,
  "renews_at": "2026-08-18T00:00:00Z",
  "status": "active"
}

401

Unauthorized

503

Billing not configured

Delete your own account

Cancels the caller's subscription at the payment provider and purges their transcript-api data (API keys, jobs, usage). Irreversible.

curl -X DELETE https://api.techtuel.com/v1/account \
  -H "Authorization: Bearer txl_your_api_key"

401

Unauthorized

500

Internal Server Error

502

Subscription cancellation failed; nothing was deleted