API Reference

Base URL

https://api.icana.ai/api/v1

Authentication

All API requests require an API key passed in the X-API-Key header.

X-API-Key: sk_test_your_api_key_here

Rate Limiting

API endpoints are rate limited per API key. When you exceed a rate limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait.

Endpoint	Rate Limit
POST /v1/transcribe	10 requests per minute
All other endpoints	60 requests per minute

Example 429 Response

{
  "detail": "Rate limit exceeded. Please retry later."
}

The response includes a Retry-After header with the number of seconds to wait before retrying.

POST /v1/transcribe

Submit an audio file for transcription and speaker diarization.

Request

Content-Type: multipart/form-data

Parameter	Type	Required	Description
file	file	Yes	Audio file (MP3, WAV, OGG, FLAC, M4A)
language	string	No	Language code (default: "en")
prompt	string	No	Comma-separated words or phrases to help the model spell specialised terms, abbreviations, or names that appear in the recording (e.g. `"ACME Corp, KPIs, Dr. Nguyen"`). Only the last ~200 tokens (~40–60 words) are used, so keep it concise.

Response

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "message": "Job submitted successfully. Poll the status endpoint to check progress."
}

GET /v1/jobs/{job_id}

Get the status and results of a transcription job.

Path Parameters

Parameter	Type	Description
job_id	UUID	The job ID returned from /transcribe

Response (Processing)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "original_filename": "audio.mp3",
  "language": "en",
  "created_at": "2025-02-03T10:30:00Z"
}

Response (Completed)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "original_filename": "audio.mp3",
  "language": "en",
  "audio_duration_seconds": 180,
  "audio_duration_minutes": 3.0,
  "transcription": "Hello, this is the full transcription...",
  "diarization": "[Speaker 1]: Hello...\n[Speaker 2]: Hi there...",
  "created_at": "2025-02-03T10:30:00Z",
  "completed_at": "2025-02-03T10:32:00Z"
}

GET /v1/jobs

List all transcription jobs for your account.

Query Parameters

Parameter	Type	Default	Description
page	int	1	Page number
page_size	int	20	Items per page (max 100)
status	string	-	Filter by status (pending, processing, completed, failed)

GET /v1/usage

Get usage summary for the current billing period.

Response

{
  "billing_period_start": "2025-02-01",
  "billing_period_end": "2025-02-28",
  "included_minutes": 500,
  "minutes_used": 123.45,
  "minutes_remaining": 376.55,
  "overage_minutes": 0,
  "overage_rate_cents": 25,
  "estimated_overage_cost_cents": 0,
  "plan_name": "Professional"
}

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters or file format
401	Unauthorized - Invalid or missing API key
402	Payment Required - Insufficient credit balance
404	Not Found - Job doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error