# TataText API

TataText is an AI-powered audio and video transcription service. Authenticated users can submit files programmatically using an API key obtained from their dashboard.

## Authentication

All API requests must include the user's API key in the request header:

```
X-API-Key: tt_<your_key>
```

API keys are generated (or regenerated) from the user's dashboard at `/dashboard`, in the "API Access" section at the bottom of the page.

Regenerating a key immediately invalidates the previous one.

---

## Endpoints

### Submit a file for transcription

```
POST https://tatatext.com/api/jobs
```

**Headers**
```
X-API-Key: tt_<your_key>
```

**Body** — `multipart/form-data`

| Field        | Type   | Required | Description                                                |
|--------------|--------|----------|------------------------------------------------------------|
| `file`       | File   | Yes      | Audio or video file to transcribe                          |
| `language`   | string | No       | BCP-47 language code, e.g. `en`, `el`, `es` (default: `en`) |
| `speakerHint`| string | No       | Expected number of speakers, e.g. `2`, or `auto` (default: `auto`) |

**Response `202 Accepted`**
```json
{
  "jobId": "job_abc123",
  "message": "Job created successfully",
  "credits": {
    "remainingMinutes": 82,
    "totalMinutes": 116
  }
}
```

**Error responses**
- `401` — Missing or invalid API key
- `429` — No transcription minutes remaining
- `400` — No file provided
- `500` — Internal error

---

### Poll job status

```
GET https://tatatext.com/api/jobs/[jobId]
```

**Headers**
```
X-API-Key: tt_<your_key>
```

**Response**
```json
{
  "id": "job_abc123",
  "status": "completed",
  "statusMessage": "Done",
  "percent": 100,
  "createdAt": 1719400000000,
  "completedAt": 1719400045000,
  "result": {
    "transcript": "Hello, welcome to the meeting...",
    "summary": "A brief summary of the content.",
    "language": "en",
    "duration": 312,
    "speakers": 2,
    "vtt": "WEBVTT\n\n00:00:00.000 --> 00:00:03.500\nHello...",
    "segments": [...]
  },
  "credits": {
    "remainingMinutes": 82,
    "totalMinutes": 116
  }
}
```

`credits` is only present when `status` is `"completed"`. While polling with status `"pending"` or `"processing"`, it will be absent (`undefined`). Check `credits` after the job completes to know how many minutes the user has left.

**`status` values:** `pending` | `processing` | `completed` | `failed`

---

### List your jobs

```
GET https://tatatext.com/api/jobs
```

**Headers**
```
X-API-Key: tt_<your_key>
```

Returns all jobs for the authenticated user (most recent first).

---

## Credits & billing

Transcription minutes are deducted from the user's account exactly as if submitted via the web interface. The deduction is based on the actual duration of the audio/video file. If the user has no remaining minutes, the API returns `429`.

After submitting a job (`POST /api/jobs`) the response immediately includes `credits.remainingMinutes` — this is the balance *before* the file is processed (duration not yet known). The authoritative post-deduction balance is returned in the `GET /api/jobs/[jobId]` response once `status` is `"completed"`.

---

## Example — curl

```bash
# Submit a file
curl -X POST https://tatatext.com/api/jobs \
  -H "X-API-Key: tt_your_key_here" \
  -F "file=@interview.mp3" \
  -F "language=en" \
  -F "speakerHint=2"

# Poll for result (replace JOB_ID)
curl https://tatatext.com/api/jobs/JOB_ID \
  -H "X-API-Key: tt_your_key_here"
```

## Example — Python

```python
import requests, time

API_KEY = "tt_your_key_here"
BASE = "https://tatatext.com/api"

# Submit
with open("interview.mp3", "rb") as f:
    r = requests.post(f"{BASE}/jobs",
        headers={"X-API-Key": API_KEY},
        files={"file": f},
        data={"language": "en", "speakerHint": "2"})
    r.raise_for_status()
    job_id = r.json()["jobId"]

# Poll until done
while True:
    r = requests.get(f"{BASE}/jobs/{job_id}", headers={"X-API-Key": API_KEY})
    job = r.json()
    if job["status"] in ("completed", "failed"):
        break
    time.sleep(5)

print(job.get("result", {}).get("transcript"))
```