# Authenticating to the ConvertAudioToText API

The public transcription API is served at:

- `https://convertaudiototext.com/v1`
- `https://api.convertaudiototext.com/v1` (same API, direct origin)

Machine-readable spec: <https://convertaudiototext.com/openapi.yaml>
API catalog (RFC 9727): <https://convertaudiototext.com/.well-known/api-catalog>

## API keys

Every `/v1` request is authenticated with an **API key**, sent as a **Bearer
token** in the `Authorization` header:

```
Authorization: Bearer ck_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Keys have one of two prefixes:

- `ck_live_` — production key.
- `ck_test_` — test key.

Session JWTs are **not** accepted on `/v1`; only `ck_live_`/`ck_test_` keys work
there.

## Where to get a key

Create and manage keys in the dashboard at
<https://convertaudiototext.com/dashboard/developers>.

API access is a **paid feature**: key creation requires the **Developer** or
**Business** plan. On the free, Pro, or credit-only tiers, key creation returns
`402 Payment Required`.

## Scopes

Keys carry one or more scopes:

- `transcribe` — create transcription jobs and read/export their results.
- `read` — read-only access to account resources.
- `write` — mutate account resources.

The public `/v1` endpoints all require the **`transcribe`** scope. Newly created
keys are granted all three scopes by default.

## Endpoints

| Method | Path | Purpose |
| ------ | ---- | ------- |
| POST | `/v1/transcribe` | Create a transcription job (file upload or URL) |
| GET | `/v1/transcribe` | List jobs on the account |
| GET | `/v1/transcribe/{job_id}` | Get a job and its transcript |
| GET | `/v1/transcribe/{job_id}/srt` | Export SRT subtitles |
| GET | `/v1/transcribe/{job_id}/vtt` | Export WebVTT subtitles |
| GET | `/v1/transcribe/{job_id}/txt` | Export plain text |
| GET | `/v1/transcribe/{job_id}/json` | Export structured JSON |

## Example

```bash
# Create a job from a URL
curl -X POST https://convertaudiototext.com/v1/transcribe \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{"source":"url","input_url":"https://example.com/audio.mp3","language":"en"}'

# Response: 201 { "job_id": "...", "status": "queued", "message": "..." }

# Poll for the result until status is "completed"
curl https://convertaudiototext.com/v1/transcribe/JOB_ID \
  -H "Authorization: Bearer ck_live_..."
```

## Errors

- `401 Unauthorized` — missing or invalid key (session JWTs are rejected here).
- `403 Forbidden` — the key is valid but lacks the `transcribe` scope.
- `402 Payment Required` — no transcription minutes left, or the plan has no API access.
- `404 Not Found` — the job id does not belong to this account.
- `429 Too Many Requests` — rate limit exceeded.