Skip to content

API Endpoints

Base URL: https://api.icana.ai

All endpoints (except Health Check) require authentication via the X-API-Key header. See Authentication.

Health Check

Verify the API is running.

GET /health

Response 200

{
  "status": "healthy",
  "message": "API is running."
}

Upload Audio File

Upload an audio file to S3 for later transcription.

POST /upload

Request

Content-Type: multipart/form-data

Parameter Type In Required Description
file file formData Yes The audio file to upload
X-API-Key string header Yes Your API key

Example

curl -X POST https://api.icana.ai/upload \
  -H "X-API-Key: your-api-key" \
  -F "file=@meeting.mp3"

Response 200

{
  "message": "File uploaded successfully",
  "s3_uri": "s3://your-upload-bucket/unique-id/your_file.mp3",
  "original_filename": "your_file.mp3",
  "job_id_suggestion": "unique-id"
}

Tip

Save the s3_uri from the response — you'll need it when submitting the transcription job.

Errors

Status Description
400 No file part or no selected file
401 Invalid or missing API key
500 Server configuration error or S3 upload failure

Submit Transcription

Submit an uploaded audio file for transcription and diarisation via AWS Batch.

POST /transcribe

Request

Content-Type: application/json

Parameter Type Required Description
s3_uri string Yes The S3 URI of the audio file (from the upload response)
language string No Language for Whisper transcription (e.g., en, es, fr). Default: en
prompt string No Optional initial prompt for Whisper to guide transcription

Example

curl -X POST https://api.icana.ai/transcribe \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "s3_uri": "s3://your-upload-bucket/unique-id/your_file.mp3",
    "language": "en",
    "prompt": "This is a customer service call."
  }'

Response 200

{
  "message": "Batch job submitted successfully",
  "aws_batch_job_id": "your-aws-batch-job-id",
  "batch_job_name": "whisper-pyannote-job-unique-id"
}

Tip

Save the aws_batch_job_id — you'll use it to check the transcription status and retrieve results.

Errors

Status Description
400 Missing s3_uri or invalid JSON
401 Invalid or missing API key
500 Server configuration error or Batch job submission failure

Check Transcription Status

Check the status of a transcription job and retrieve results when complete.

GET /status/{aws_batch_job_id}

Parameters

Parameter Type In Required Description
aws_batch_job_id string path Yes The AWS Batch Job ID
X-API-Key string header Yes Your API key

Example

curl https://api.icana.ai/status/your-aws-batch-job-id \
  -H "X-API-Key: your-api-key"

Response 200 — Completed

{
  "aws_batch_job_id": "your-aws-batch-job-id",
  "status": "COMPLETE",
  "message": "Batch job completed successfully.",
  "transcription": "This is the transcribed text.",
  "diarization": "[ 0m0s - 0m5s ] Speaker 1: Hello world."
}

Response 200 — Processing

{
  "aws_batch_job_id": "your-aws-batch-job-id",
  "status": "PROCESSING",
  "message": "Batch job is still processing."
}

Job Statuses

Status Description
PROCESSING The job is currently being processed
COMPLETE Transcription finished successfully — results are included
FAILED The job failed
DELETED The job outputs have been deleted
NOT_FOUND The job ID was not found
UNKNOWN Status could not be determined
ERROR An error occurred while checking status

Errors

Status Description
401 Invalid or missing API key
404 AWS Batch Job ID not found
500 Server configuration error or unexpected error

Queue Status

Get a summary of jobs currently in the processing queue.

GET /queue/status

Parameters

Parameter Type In Required Description
X-API-Key string header Yes Your API key

Example

curl https://api.icana.ai/queue/status \
  -H "X-API-Key: your-api-key"

Response 200

{
  "total_jobs": 10,
  "status_counts": {
    "SUBMITTED": 2,
    "PENDING": 3,
    "RUNNABLE": 5,
    "STARTING": 0
  }
}

Errors

Status Description
401 Invalid or missing API key
500 Server configuration error or unexpected error

Delete Transcription Files

Delete input and output files associated with a transcription job.

DELETE /delete/{aws_batch_job_id}

Parameters

Parameter Type In Required Description
aws_batch_job_id string path Yes The AWS Batch Job ID
X-API-Key string header Yes Your API key
s3_uri string body Yes The S3 URI of the original input file

Example

curl -X DELETE https://api.icana.ai/delete/your-aws-batch-job-id \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "s3_uri": "s3://your-upload-bucket/unique-id/your_file.mp3"
  }'

Response 200

{
  "message": "Files deleted successfully.",
  "input_file_deleted": true,
  "output_files_deleted": [
    "job-id.json",
    "job-id_diarization.txt"
  ]
}

Errors

Status Description
400 Missing s3_uri or invalid S3 URI
401 Invalid or missing API key
500 Server configuration error or unexpected error during deletion