API Reference¶
Last updated: 2026-10-13
This page serves as a reference for all endpoints available for Kawa services.
The parameter, field and status code tables are generated from the OpenAPI specification (openapi.json) each time the site is built, so they always match it. The examples and guidance between them are written by hand.
Errors come in two kinds. A request that is refused gets an HTTP error at once; each endpoint's status codes below list them. A job that was accepted but then failed reports why in its error; every code is listed in Job Errors.
To try these endpoints without writing code, fork the Kawa collection into your own Postman workspace. In your fork, set the raw_api_key collection variable to your API key; every request authenticates with it from there.
POST /v1/transcriptions¶
Create a transcription job.
Create a transcription from an audio file (MP3 or WAV only), sent one of two ways:
multipart/form-data: the file in the request itself. The request passes through API Gateway and Lambda, so files above about 4 MB are rejected before they reach this API: use the second way for those.application/jsonwith anupload_id: the file was first sent straight to storage throughPOST /v1/uploads(up to 15 MB). One upload makes at most one job: repeating the request returns that same job with200, so a request whose response was lost is safe to send again. A job that failed is not retried this way; upload the file again.
The job is submitted to the transcription provider and returns immediately with status processing; the transcript is delivered asynchronously and retrieved via GET /v1/transcriptions/{job_id}.
Request Body (multipart/form-data)¶
| Field | Type | Required | Description |
|---|---|---|---|
file |
string (binary) | Yes | Audio file to transcribe. Above about 4 MB the gateway rejects the request: use POST /v1/uploads for those (up to 15 MB). |
language |
string | No | Optional ISO 639-1 language code, such as en. Omit it to detect the language. |
metadata |
string | No | Optional JSON-encoded object echoed back on the job. Must be a valid JSON string. Example: {"call_id":"abc-123"}. |
flow_run_id |
string (uuid) | No | Internal use: attaches this job to a Flow run (the dashboard's visual workflow builder), if this job is one step of a Flow. Must refer to a run you own. |
Request Body (application/json)¶
| Field | Type | Required | Description |
|---|---|---|---|
upload_id |
string (uuid) | Yes | From POST /v1/uploads, once its file has been sent. |
language |
string | No | Optional ISO 639-1 language code, such as en. Omit it to detect the language. |
metadata |
object | No | Optional object echoed back on the job. A JSON-encoded string is accepted too, as in the multipart form. |
flow_run_id |
string (uuid) | No | Internal use: attaches this job to a Flow run (the dashboard's visual workflow builder), if this job is one step of a Flow. Must refer to a run you own. |
Response Body (200)¶
| Field | Type | Description |
|---|---|---|
job_id |
string (uuid) | |
status |
string | Lifecycle of a job: queued on creation, processing once submitted to the provider, then succeeded or failed. |
received_at |
string (date-time) |
Response Body (202)¶
| Field | Type | Description |
|---|---|---|
job_id |
string (uuid) | |
status |
string | Lifecycle of a job: queued on creation, processing once submitted to the provider, then succeeded or failed. |
received_at |
string (date-time) |
Status Codes¶
| Status | Meaning |
|---|---|
200 |
This upload_id already has its job, from an earlier request. Nothing new is created, and this request's other fields are ignored; the body describes that job in its current status. If that job failed, upload the file again to try once more. |
202 |
Job accepted and submitted to the provider. |
400 |
No audio file provided (AUDIO_FILE_MISSING), the audio's duration could not be determined (AUDIO_DURATION_UNKNOWN), metadata is not valid JSON (INVALID_METADATA_JSON), language is not a string of at most 32 characters (INVALID_LANGUAGE), flow_run_id is present but whitespace-only or doesn't refer to a run the caller owns (INVALID_FLOW_RUN_ID), or, for a JSON body, the body is not valid JSON (INVALID_JSON_BODY) or has no upload_id (MISSING_UPLOAD_ID). |
401 |
Missing or invalid bearer token. |
404 |
No upload with that upload_id belongs to the caller, or the job made from it has been deleted (UPLOAD_NOT_FOUND). |
409 |
The upload exists but no file has arrived for it, or it is no longer stored (UPLOAD_NOT_READY): for example, the presigned form expired unused, or an earlier request for it was turned away and its file discarded. Send the file first, or start a new upload. |
413 |
File exceeds the 15 MB limit (a multipart request is rejected by the gateway above about 4 MB, before this check; use an upload for larger files). details gives max_bytes and the upload's size_bytes. |
415 |
Unsupported audio format. Only MP3 and WAV are accepted; details.allowed_extensions lists them. |
429 |
Accepting this file would take the caller past their transcription minute quota. No job is created. details gives limit_minutes, used_minutes and this file's file_minutes. The developer portal shows the same quota. |
500 |
Internal server error. |
502 |
The job was stored but submission to the transcription provider failed. The job is marked failed with error.code provider_submit_failed. |
Example¶
Request:
curl -sS -X POST "${MAKIMOTO_API_URL}/v1/transcriptions" \
-H "Authorization: Bearer ${MAKIMOTO_API_KEY}" \
-F "file=@samples-audio/harvard.wav" \
-F "language=en" \
-F 'metadata={"call_id":"abc-123"}'
Success (202):
{
"job_id": "b3f1c2a4-9d7e-4a1b-8c2f-1e5d6a7b8c90",
"status": "processing",
"received_at": "2026-07-01T09:15:23.412Z",
"requestId": "a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7"
}
Poll for the result:
curl -sS "${MAKIMOTO_API_URL}/v1/transcriptions/b3f1c2a4-9d7e-4a1b-8c2f-1e5d6a7b8c90" \
-H "Authorization: Bearer ${MAKIMOTO_API_KEY}"
Succeeded (200), once the transcript is ready:
{
"job_id": "b3f1c2a4-9d7e-4a1b-8c2f-1e5d6a7b8c90",
"status": "succeeded",
"type": "transcription",
"result": {
"language": "en",
"duration_seconds": 18,
"words_count": 48,
"transcript": [
{ "text": "The birch canoe slid on the smooth planks.", "time_start": 0.0, "time_end": 3.1, "speaker_id": 0, "speaker_alias": "User" },
{ "text": "Glue the sheet to the dark blue background.", "time_start": 3.4, "time_end": 6.6, "speaker_id": 0, "speaker_alias": "User" }
]
},
"requestId": "d4e5f6a7-b8c9-4012-d3e4-f5a6b7c8d9e0"
}
Failure (415 UNSUPPORTED_AUDIO_FORMAT), for example uploading an .m4a file:
{
"error": { "code": "UNSUPPORTED_AUDIO_FORMAT", "message": "Unsupported audio format. Only MP3 and WAV are accepted." },
"requestId": "b2c3d4e5-f6a7-4890-b1c2-d3e4f5a6b7c8"
}
Every error response carries this same envelope: a machine-readable code and message, plus the same top-level requestId as a successful one. QUOTA_EXCEEDED also carries error.details:
{
"error": { "code": "QUOTA_EXCEEDED", "message": "Transcription minute quota exceeded.", "details": { "limit_minutes": 1000, "used_minutes": 998.2, "file_minutes": 5.0 } },
"requestId": "d4e5f6a7-b8c9-40d1-92e3-f4a5b6c7d8e9"
}
Supported Audio and Limits¶
| Constraint | Value | Response if exceeded |
|---|---|---|
| Formats | MP3 and WAV only | 415 Unsupported Media Type |
| Maximum file size | 15 MB through POST /v1/uploads; about 4 MB for a file sent in the request itself |
413 Payload Too Large |
| Audio content | Must be decodable with a readable duration | 400 Bad Request |
| Account quota | 1000 minutes of audio per month on the free allowance (failed jobs are not counted) | 429 Too Many Requests |
Both single-channel (mono) and dual-channel (stereo) audio are accepted; see Diarisation below for how channel count affects speaker separation.
Note
A supposed single-speaker mono audio file can actually be a stereo audio file, with mono audio duplicated in both channels (conversion could happen when downloading the audio, for instance). Therefore, the output may appear duplicated for both speakers, when there is only one speaker in the audio.
Recommended encoding: WAV, 16-bit PCM, at a sample rate between 8 kHz (telephone band) and 16 kHz, which is plenty for speech.
The 15 MB cap is reached at very different durations depending on encoding, so choose the format to fit the clip:
| Encoding | Approx. minutes in 15 MB |
|---|---|
| WAV PCM 16-bit, 8 kHz, stereo | ~8 |
| WAV PCM 16-bit, 8 kHz, mono | ~16 |
| MP3 128 kbps | ~16 |
| MP3 32 kbps | ~65 |
Tip
For anything longer than a short clip, try using MP3 or downmix WAV to mono to stay under the cap. The repository's samples-audio/ directory contains ready-to-use test files in the supported formats.
Diarisation¶
Diarisation is currently stereo-only: the pipeline splits the two channels (left/right) and diarises by channel, rather than separating speakers within a single mixed signal. Each channel maps to a speaker index, labeled speaker_id: 0 and speaker_id: 1.
POST /v1/uploads¶
Start a presigned upload.
The first step of transcribing a file too large to send through POST /v1/transcriptions (anything above about 4 MB, up to 15 MB). Returns an upload_id and a presigned form: send the file to upload.url as multipart/form-data, with every entry of upload.fields first and the file (field name file) last, before expires_at. Storage itself enforces the declared content_type and the size limit. Then call POST /v1/transcriptions with { "upload_id": ... }. A file that no transcription claims is deleted within a day. Refused with 429 once the caller's minute quota is used up.
Request Body (application/json)¶
| Field | Type | Required | Description |
|---|---|---|---|
filename |
string | Yes | The file's original name, returned as the job's original_filename. Example: call.mp3. |
content_type |
string | Yes | The file's type. The upload must send this exact Content-Type, which upload.fields already carries. One of audio/mpeg, audio/mp3, audio/wav, audio/x-wav, audio/wave, audio/vnd.wave. |
Response Body (201)¶
| Field | Type | Description |
|---|---|---|
upload_id |
string (uuid) | |
upload |
object | A presigned form. POST it to url as multipart/form-data: every entry of fields first, then the file as file. |
upload.url |
string (uri) | |
upload.fields |
map of string | |
expires_at |
string (date-time) | The form is refused after this: normally 15 minutes ahead, occasionally sooner. |
max_bytes |
integer | Largest file the form accepts. |
Status Codes¶
| Status | Meaning |
|---|---|
201 |
Upload started. Send the file to upload.url before expires_at. |
400 |
Body is not valid JSON (INVALID_JSON_BODY), or filename is missing or longer than 255 characters (INVALID_FILENAME). |
401 |
Missing or invalid bearer token. |
415 |
Unsupported audio format. Only MP3 and WAV are accepted; details.allowed_extensions lists them. |
429 |
No new upload can start: the caller's minute quota is used up (QUOTA_EXCEEDED, with limit_minutes and used_minutes), or 20 uploads from the last day are still waiting for a transcription (TOO_MANY_OPEN_UPLOADS, with max_open_uploads). Transcribe one, or start more later. |
500 |
Internal server error. |
Example¶
A file too large to send in the request itself (above about 4 MB) goes in three steps: start an upload, send the file straight to storage, then create the transcription from it.
1. Start the upload. Request:
curl -sS -X POST "${MAKIMOTO_API_URL}/v1/uploads" \
-H "Authorization: Bearer ${MAKIMOTO_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"filename": "call.mp3", "content_type": "audio/mpeg"}' > upload.json
Success (201):
{
"upload_id": "5b0e7c2a-3f4d-4e8a-9b1c-2d3e4f5a6b7c",
"upload": {
"url": "https://example-audio-bucket.s3.ap-southeast-1.amazonaws.com/",
"fields": {
"Content-Type": "audio/mpeg",
"key": "audio/.../5b0e7c2a-3f4d-4e8a-9b1c-2d3e4f5a6b7c.mp3",
"Policy": "...",
"X-Amz-Signature": "..."
}
},
"expires_at": "2026-10-28T10:15:00.000Z",
"max_bytes": 15728640
}
fields holds more entries than shown here; send them all, unchanged.
2. Send the file to upload.url before expires_at, as multipart/form-data: every entry of upload.fields first, then the file as file. No API key: the form itself is the permission.
form=()
while IFS= read -r field; do form+=(-F "$field"); done \
< <(jq -r '.upload.fields | to_entries[] | "\(.key)=\(.value)"' upload.json)
curl -sS -X POST "$(jq -r .upload.url upload.json)" "${form[@]}" -F "file=@call.mp3"
Storage answers 204 with an empty body. It refuses an empty file, one larger than max_bytes, or a form whose fields were changed.
3. Create the transcription with the upload_id, as JSON instead of a file. language and metadata work as they do for a file sent in the request:
curl -sS -X POST "${MAKIMOTO_API_URL}/v1/transcriptions" \
-H "Authorization: Bearer ${MAKIMOTO_API_KEY}" \
-H "Content-Type: application/json" \
-d "{\"upload_id\": \"$(jq -r .upload_id upload.json)\", \"language\": \"en\"}"
The response is the same 202 as POST /v1/transcriptions. One upload makes one job: sending this request again returns that job with 200, so it is safe to retry if a response was lost. An upload that no transcription uses is deleted within a day.
GET /v1/transcriptions¶
List the caller's transcription jobs.
Returns the caller's jobs, most recent first. Supports pagination (limit/cursor) and filtering by status, type, language, created_after, and job_id, which compose with AND when combined. The cursor only encodes position, not which filters were active, so resend the same filter params on every paginated request or the result set can change partway through.
Query Parameters¶
| Parameter | Type | Required | Description |
|---|---|---|---|
limit |
integer | No | Max jobs to return. Default 10, max 100 (values above 100 are silently capped, not rejected). |
cursor |
string | No | Opaque pagination cursor from a previous response's next_cursor. Omit for the first page. Not meant to be constructed or decoded by clients, its internal shape may change. |
status |
string | No | Only return jobs with this status. One of queued, processing, succeeded, failed. |
type |
string | No | Only return jobs of this type. One of transcription, summary, tags. |
language |
string | No | Only return jobs with this exact language value. Example: en. |
created_after |
string (date-time) | No | Only return jobs created after this ISO 8601 timestamp. Example: 2026-06-01T00:00:00Z. |
job_id |
string (uuid) | No | Only return the job with this exact ID. An exact match, not a search, a malformed UUID is rejected with 400. |
flow_run_id |
string (uuid) | No | Internal use: only return jobs created as one step of a Flow run (the dashboard's visual workflow builder). A malformed UUID is rejected with 400. |
Response Body (200)¶
| Field | Type | Description |
|---|---|---|
transcriptions |
array of object | |
transcriptions[].job_id |
string (uuid) | |
transcriptions[].type |
string | What a job represents, and therefore which shape its result carries: transcription a transcript, summary a topic and a summary, tags a tag set. |
transcriptions[].status |
string | Lifecycle of a job: queued on creation, processing once submitted to the provider, then succeeded or failed. |
transcriptions[].original_filename |
string | |
transcriptions[].language |
string, nullable | |
transcriptions[].audio_seconds |
integer | Audio duration in seconds. 0 for a summary or tags job, whose seconds were already metered by the transcription it was derived from. |
transcriptions[].flow_run_id |
string (uuid), nullable | Which Flow run this job was one step of, if any - null for a Playground run or a direct API call. |
transcriptions[].trace_id |
string, nullable | W3C trace id of the request that created this job, followed through every later step of the job. Quote it with the job id when reporting a problem. Null for jobs created before tracing was enabled. Example: 4bf92f3577b34da6a3ce929d0e0e4736. |
transcriptions[].error |
object | Present when the job has failed. Same as on Get a job. |
transcriptions[].error.code |
string | Why the job failed. Match on this, not on message. New codes may be added; treat an unknown code as a generic failure. - invalid_audio: The audio could not be decoded. Check that the file is a complete recording in a supported audio format, then submit it again. - provider_no_transcript: The transcription could not be completed. Check that the recording contains speech, then submit it again. If it fails again, report the problem with the job ID. - transcription_timeout: Transcription took too long and was stopped. Try a shorter recording, or split a long one into parts. If a short recording times out, report the problem with the job ID. - unsupported_language: The requested language is not supported. Use an ISO 639-1 language code such as en, or leave the language out to have it detected. - no_summary: No summary could be made from this transcript. This is a result, not a fault: retrying the same transcript gives the same answer. - no_tags: No tags could be found in this transcript. This is a result, not a fault: retrying the same transcript gives the same answer. - provider_postprocessing_failed: The summary or tags could not be produced. Submit the request again. If it fails again, report the problem with the job ID. - provider_submit_failed: The job could not be sent for processing. Submit the job again in a few minutes. If it keeps failing, report the problem with the job ID. - queue_timeout: Job waited too long in the queue without being sent. Submit the job again. If it keeps happening, report the problem with the job ID. - reconciliation_timeout: Job exceeded the maximum time allowed without a provider callback. Submit the job again. If it keeps happening, report the problem with the job ID. |
transcriptions[].error.message |
string | The cause, in plain words. Wording may change; match on code. |
transcriptions[].error.next_step |
string | What to do about it. Wording may change. |
transcriptions[].error.docs_url |
string (uri) | This code's entry on the job errors page, or the page itself for an unknown code. Example: https://docs.makimoto.ai/service/job-errors/#invalid_audio. |
transcriptions[].error.provider_error |
object | The processing service's own code and message, for Makimoto support. May change without notice; match on code instead. |
transcriptions[].error.provider_error.code |
string | |
transcriptions[].error.provider_error.message |
string | |
transcriptions[].created_at |
string (date-time) | |
transcriptions[].updated_at |
string (date-time) | |
next_cursor |
string, nullable | Opaque cursor for the next page, or null if this is the last page. |
total |
integer | Jobs matching the current filters across every page, not just the ones in transcriptions. Counted under the same filters as the list, so it changes as filters change, and is unaffected by cursor or limit. |
Status Codes¶
| Status | Meaning |
|---|---|
200 |
List of the caller's jobs. |
401 |
Missing or invalid bearer token. |
500 |
Internal server error. |
The cursor only encodes position, not which filters were active, so resend the same filter parameters on every paginated request, or the result set can shift partway through.
Example 200 Response (a single job, well within the default limit of 10):
{
"transcriptions": [
{
"job_id": "b3f1c2a4-9d7e-4a1b-8c2f-1e5d6a7b8c90",
"type": "transcription",
"status": "succeeded",
"original_filename": "harvard.wav",
"language": "en",
"audio_seconds": 18,
"created_at": "2026-07-01T09:15:23.412Z",
"updated_at": "2026-07-01T09:15:41.902Z"
}
],
"next_cursor": null,
"requestId": "b2c3d4e5-f6a7-4890-b1c2-d3e4f5a6b7c8"
}
Example request for the next page of a larger list, filtered to succeeded transcriptions only:
curl -sS "${MAKIMOTO_API_URL}/v1/transcriptions?status=succeeded&type=transcription&limit=25&cursor=${NEXT_CURSOR}" \
-H "Authorization: Bearer ${MAKIMOTO_API_KEY}" | jq
GET /v1/transcriptions/{job_id}¶
Get a job.
Returns the job status. When succeeded, the result block is included; when failed, the error block is included.
Serves all three job types: type says whether result is a transcript, a summary or a tag set. A summary or tags job is polled here using the job_id its own POST returned, not the transcription's id.
Path Parameters¶
| Parameter | Type | Required | Description |
|---|---|---|---|
job_id |
string (uuid) | Yes | The transcription job identifier. |
Response Body (200)¶
| Field | Type | Description |
|---|---|---|
job_id |
string (uuid) | |
type |
string | What a job represents, and therefore which shape its result carries: transcription a transcript, summary a topic and a summary, tags a tag set. |
status |
string | Lifecycle of a job: queued on creation, processing once submitted to the provider, then succeeded or failed. |
source_job_id |
string (uuid) | The transcription this job was derived from. Present on a summary or tags job created after the pairing began being recorded; absent on a transcription, which has no source, and on older postprocessing jobs. |
input_text |
string | The exact text a summary or tags job sent for processing: the flattened transcript (one speaker: text line per turn) when created from transcription_job_id, or the trimmed transcript_text otherwise. Absent on a transcription and on older postprocessing jobs. |
result |
one of TranscriptionResult, SummaryResult, TagsResult |
Present when the job has succeeded. Which of the three shapes it takes is given by type. |
error |
object | Present when the job has failed. |
error.code |
string | Why the job failed. Match on this, not on message. New codes may be added; treat an unknown code as a generic failure. - invalid_audio: The audio could not be decoded. Check that the file is a complete recording in a supported audio format, then submit it again. - provider_no_transcript: The transcription could not be completed. Check that the recording contains speech, then submit it again. If it fails again, report the problem with the job ID. - transcription_timeout: Transcription took too long and was stopped. Try a shorter recording, or split a long one into parts. If a short recording times out, report the problem with the job ID. - unsupported_language: The requested language is not supported. Use an ISO 639-1 language code such as en, or leave the language out to have it detected. - no_summary: No summary could be made from this transcript. This is a result, not a fault: retrying the same transcript gives the same answer. - no_tags: No tags could be found in this transcript. This is a result, not a fault: retrying the same transcript gives the same answer. - provider_postprocessing_failed: The summary or tags could not be produced. Submit the request again. If it fails again, report the problem with the job ID. - provider_submit_failed: The job could not be sent for processing. Submit the job again in a few minutes. If it keeps failing, report the problem with the job ID. - queue_timeout: Job waited too long in the queue without being sent. Submit the job again. If it keeps happening, report the problem with the job ID. - reconciliation_timeout: Job exceeded the maximum time allowed without a provider callback. Submit the job again. If it keeps happening, report the problem with the job ID. |
error.message |
string | The cause, in plain words. Wording may change; match on code. |
error.next_step |
string | What to do about it. Wording may change. |
error.docs_url |
string (uri) | This code's entry on the job errors page, or the page itself for an unknown code. Example: https://docs.makimoto.ai/service/job-errors/#invalid_audio. |
error.provider_error |
object | The processing service's own code and message, for Makimoto support. May change without notice; match on code instead. |
error.provider_error.code |
string | |
error.provider_error.message |
string |
result as TranscriptionResult:
| Field | Type | Description |
|---|---|---|
language |
string, nullable | |
duration_seconds |
integer, nullable | |
words_count |
integer, nullable | |
transcript |
array of object | |
transcript[].text |
string | |
transcript[].time_start |
number (float) | Segment start, in seconds. |
transcript[].time_end |
number (float) | Segment end, in seconds. |
transcript[].speaker_id |
integer | |
transcript[].speaker_alias |
string |
result as SummaryResult:
| Field | Type | Description |
|---|---|---|
topic |
string, nullable | Short label for what the call was about. Null when the model produced none. |
summary |
string | Prose summary of the conversation. |
meta_data |
object, nullable | Generation metadata reported by the provider (model, batch size, timing). Passed through unread. |
result as TagsResult:
| Field | Type | Description |
|---|---|---|
tags |
map of array of string | Tag category to selected values. Category keys are lower_snake_case. |
meta_data |
object, nullable |
Status Codes¶
| Status | Meaning |
|---|---|
200 |
The job, with result (succeeded) or error (failed) when available. |
401 |
Missing or invalid bearer token. |
403 |
The job does not belong to the caller. |
404 |
No job with that identifier. |
500 |
Internal server error. |
Example 200 Response (succeeded, type: transcription):
{
"job_id": "b3f1c2a4-9d7e-4a1b-8c2f-1e5d6a7b8c90",
"status": "succeeded",
"type": "transcription",
"result": {
"language": "en",
"duration_seconds": 18,
"words_count": 48,
"transcript": [
{ "text": "The birch canoe slid on the smooth planks.", "time_start": 0.0, "time_end": 3.1, "speaker_id": 0, "speaker_alias": "User" },
{ "text": "Glue the sheet to the dark blue background.", "time_start": 3.4, "time_end": 6.6, "speaker_id": 0, "speaker_alias": "User" }
]
},
"requestId": "d4e5f6a7-b8c9-4012-d3e4-f5a6b7c8d9e0"
}
Example 200 Response (succeeded, type: summary):
{
"job_id": "7e2b1a3c-4f5d-4e6a-9b8c-1d2e3f4a5b6c",
"status": "succeeded",
"type": "summary",
"source_job_id": "b3f1c2a4-9d7e-4a1b-8c2f-1e5d6a7b8c90",
"result": {
"topic": "Billing dispute",
"summary": "Customer called about a duplicate charge on their latest invoice; agent confirmed the refund and closed the ticket.",
"meta_data": null
},
"requestId": "e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1"
}
Example 200 Response (succeeded, type: tags):
{
"job_id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"status": "succeeded",
"type": "tags",
"source_job_id": "b3f1c2a4-9d7e-4a1b-8c2f-1e5d6a7b8c90",
"result": {
"tags": {
"call_reason": ["billing_issue", "refund"],
"call_outcome": ["issue_resolved"]
},
"meta_data": null
},
"requestId": "f6a7b8c9-d0e1-4234-f5a6-b7c8d9e0f1a2"
}
Example 200 Response (failed):
{
"job_id": "b3f1c2a4-9d7e-4a1b-8c2f-1e5d6a7b8c90",
"status": "failed",
"type": "transcription",
"error": {
"code": "invalid_audio",
"message": "The audio could not be decoded.",
"next_step": "Check that the file is a complete recording in a supported audio format, then submit it again.",
"docs_url": "https://docs.makimoto.ai/service/job-errors/#invalid_audio"
},
"requestId": "a7b8c9d0-e1f2-4345-a6b7-c8d9e0f1a2b3"
}
Every code a failed job can carry, with its cause and next step, is listed in Job Errors.
POST /v1/summarize¶
Summarise a transcription.
Creates a summary job from a transcript, supplied either as one of your own transcriptions that has already succeeded (transcription_job_id) or as text sent directly (transcript_text).
The second form does not involve this API's speech-to-text pipeline at all: the transcript may come from any source, and no audio, transcription job or quota is required. Only the first form can return 403, 404, 409 or 422.
Returns immediately with status queued; the summary is generated asynchronously and retrieved via GET /v1/transcriptions/{job_id} using the job_id returned here, not the transcription's own id.
Request Body (application/json)¶
Exactly one of transcription_job_id or transcript_text must be given.
| Field | Type | Required | Description |
|---|---|---|---|
transcription_job_id |
string (uuid) | No | One of your own transcription jobs, in status succeeded. Must be a transcription job, not another summary or tags job. |
transcript_text |
string | No | A transcript supplied directly, with no transcription job behind it. It need not have come from this API: another speech-to-text vendor, a chat log, a CRM export or typed notes are all accepted. Must be non-empty once trimmed. |
flow_run_id |
string (uuid) | No | Internal use: attaches this job to a Flow run (the dashboard's visual workflow builder), if this job is one step of a Flow. Must refer to a run you own, a present but invalid value is rejected with 400 rather than silently ignored. |
Response Body (202)¶
| Field | Type | Description |
|---|---|---|
job_id |
string (uuid) | The new postprocessing job. Poll this id, not the transcription's. The pairing does not need remembering: GET /v1/transcriptions/{job_id} reports it back as source_job_id. |
type |
string | What a job represents, and therefore which shape its result carries: transcription a transcript, summary a topic and a summary, tags a tag set. |
status |
string | Lifecycle of a job: queued on creation, processing once submitted to the provider, then succeeded or failed. |
received_at |
string (date-time) |
Status Codes¶
| Status | Meaning |
|---|---|
202 |
Job accepted and submitted to the summarisation provider. |
400 |
Body is not valid JSON, no transcript source (or both transcription_job_id and transcript_text) was given, transcription_job_id refers to a job that is not a transcription, or flow_run_id is present but not a non-empty string or doesn't refer to a run the caller owns (INVALID_FLOW_RUN_ID). |
401 |
Missing or invalid bearer token. |
403 |
The job does not belong to the caller. |
404 |
No job with that identifier. |
409 |
The transcription has not succeeded yet. The same request will be accepted once it has, so retry later rather than changing it. |
422 |
The transcript contains no speech to postprocess. |
500 |
Internal server error. |
502 |
The job was stored but submission to the provider failed. The job is marked failed with error.code provider_submit_failed. |
Current Behaviour and Limitations¶
The current summary feature has two caveats to take note of during use: 1. Sufficient context has to be provided to the summary in order for a summary to be generated. If the transcript provided is too short, the service may return an empty summmary instead. 2. The summary feature is optimised for a two-party telephony conversation; further behaviour customisation is in the works for a future release.
Example¶
Request, using transcript_text directly (no transcription job involved):
curl -sS -X POST "${MAKIMOTO_API_URL}/v1/summarize" \
-H "Authorization: Bearer ${MAKIMOTO_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"transcript_text":"Customer: I was charged twice for my last invoice.\nAgent: Let me pull that up and issue a refund."}'
Or, derived from an already-succeeded transcription job:
curl -sS -X POST "${MAKIMOTO_API_URL}/v1/summarize" \
-H "Authorization: Bearer ${MAKIMOTO_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"transcription_job_id":"b3f1c2a4-9d7e-4a1b-8c2f-1e5d6a7b8c90"}'
Success (202):
{
"job_id": "7e2b1a3c-4f5d-4e6a-9b8c-1d2e3f4a5b6c",
"type": "summary",
"status": "queued",
"received_at": "2026-09-15T03:00:00.000Z",
"requestId": "c9d0e1f2-a3b4-4567-c8d9-e0f1a2b3c4d5"
}
Poll for the result:
curl -sS "${MAKIMOTO_API_URL}/v1/transcriptions/7e2b1a3c-4f5d-4e6a-9b8c-1d2e3f4a5b6c" \
-H "Authorization: Bearer ${MAKIMOTO_API_KEY}"
Succeeded (200):
{
"job_id": "7e2b1a3c-4f5d-4e6a-9b8c-1d2e3f4a5b6c",
"status": "succeeded",
"type": "summary",
"source_job_id": "b3f1c2a4-9d7e-4a1b-8c2f-1e5d6a7b8c90",
"result": {
"topic": "Billing dispute",
"summary": "Customer called about a duplicate charge on their latest invoice; agent confirmed the refund and closed the ticket.",
"meta_data": null
},
"requestId": "e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1"
}
Failure (409 TRANSCRIPTION_NOT_READY), if transcription_job_id points at a transcription still queued or processing:
{
"error": { "code": "TRANSCRIPTION_NOT_READY", "message": "The transcription has not succeeded yet.", "details": { "status": "processing" } },
"requestId": "b8c9d0e1-f2a3-4456-b7c8-d9e0f1a2b3c4"
}
Every error response carries this same envelope: a machine-readable code and message, plus the same top-level requestId as a successful one.
POST /v1/tag¶
Tag a transcription.
Creates a tags job from a transcript, supplied either as one of your own transcriptions that has already succeeded (transcription_job_id) or as text sent directly (transcript_text).
The second form does not involve this API's speech-to-text pipeline at all: the transcript may come from any source, and no audio, transcription job or quota is required. Only the first form can return 403, 404, 409 or 422.
Returns immediately with status queued; the tags are generated asynchronously and retrieved via GET /v1/transcriptions/{job_id} using the job_id returned here, not the transcription's own id.
The tag taxonomy is fixed by the service and contact-centre shaped; it is not configurable per account, and does not vary with which input form was used.
Request Body (application/json)¶
Exactly one of transcription_job_id or transcript_text must be given.
| Field | Type | Required | Description |
|---|---|---|---|
transcription_job_id |
string (uuid) | No | One of your own transcription jobs, in status succeeded. Must be a transcription job, not another summary or tags job. |
transcript_text |
string | No | A transcript supplied directly, with no transcription job behind it. It need not have come from this API: another speech-to-text vendor, a chat log, a CRM export or typed notes are all accepted. Must be non-empty once trimmed. |
flow_run_id |
string (uuid) | No | Internal use: attaches this job to a Flow run (the dashboard's visual workflow builder), if this job is one step of a Flow. Must refer to a run you own, a present but invalid value is rejected with 400 rather than silently ignored. |
Response Body (202)¶
| Field | Type | Description |
|---|---|---|
job_id |
string (uuid) | The new postprocessing job. Poll this id, not the transcription's. The pairing does not need remembering: GET /v1/transcriptions/{job_id} reports it back as source_job_id. |
type |
string | What a job represents, and therefore which shape its result carries: transcription a transcript, summary a topic and a summary, tags a tag set. |
status |
string | Lifecycle of a job: queued on creation, processing once submitted to the provider, then succeeded or failed. |
received_at |
string (date-time) |
Status Codes¶
| Status | Meaning |
|---|---|
202 |
Job accepted and submitted to the tagging provider. |
400 |
Body is not valid JSON, no transcript source (or both transcription_job_id and transcript_text) was given, transcription_job_id refers to a job that is not a transcription, or flow_run_id is present but not a non-empty string or doesn't refer to a run the caller owns (INVALID_FLOW_RUN_ID). |
401 |
Missing or invalid bearer token. |
403 |
The job does not belong to the caller. |
404 |
No job with that identifier. |
409 |
The transcription has not succeeded yet. The same request will be accepted once it has, so retry later rather than changing it. |
422 |
The transcript contains no speech to postprocess. |
500 |
Internal server error. |
502 |
The job was stored but submission to the provider failed. The job is marked failed with error.code provider_submit_failed. |
Current Behaviour and Limitations¶
The current tagging service is optimised for a two-party telephony conversation, in the context of a business-customer call. As such, the tags generated may reference terminology pertaining to this context.
Tagging customisation is in the works for a future release.
Example¶
Request, tagging an already-succeeded transcription job:
curl -sS -X POST "${MAKIMOTO_API_URL}/v1/tag" \
-H "Authorization: Bearer ${MAKIMOTO_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"transcription_job_id":"b3f1c2a4-9d7e-4a1b-8c2f-1e5d6a7b8c90"}'
Success (202):
{
"job_id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"type": "tags",
"status": "queued",
"received_at": "2026-09-15T03:00:05.000Z",
"requestId": "d0e1f2a3-b4c5-4678-d9e0-f1a2b3c4d5e6"
}
Poll for the result:
curl -sS "${MAKIMOTO_API_URL}/v1/transcriptions/9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d" \
-H "Authorization: Bearer ${MAKIMOTO_API_KEY}"
Succeeded (200):
{
"job_id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"status": "succeeded",
"type": "tags",
"source_job_id": "b3f1c2a4-9d7e-4a1b-8c2f-1e5d6a7b8c90",
"result": {
"tags": {
"call_reason": ["billing_issue", "refund"],
"call_outcome": ["issue_resolved"]
},
"meta_data": null
},
"requestId": "f6a7b8c9-d0e1-4234-f5a6-b7c8d9e0f1a2"
}
Failure (422 TRANSCRIPT_EMPTY), if the source transcription succeeded but had no speech to tag:
{
"error": { "code": "TRANSCRIPT_EMPTY", "message": "The transcription contains no speech to postprocess." },
"requestId": "f1a2b3c4-d5e6-4789-a0b1-c2d3e4f5a6b7"
}
Every error response carries this same envelope: a machine-readable code and message, plus the same top-level requestId as a successful one.
DELETE /v1/transcriptions/{job_id}¶
Delete a job.
Removes the source audio from storage immediately and flags the job for scheduled deletion per the retention policy. Once flagged, the job reads as 404 on every route.
Accepts any of the three job types. A summary or tags job has no audio of its own, so for those only the scheduled deletion applies. Deleting a transcription does not delete summaries or tags derived from it: delete those by their own job_id.
Path Parameters¶
| Parameter | Type | Required | Description |
|---|---|---|---|
job_id |
string (uuid) | Yes | The transcription job identifier. |
Status Codes¶
| Status | Meaning |
|---|---|
202 |
Deletion accepted. Empty body. |
401 |
Missing or invalid bearer token. |
403 |
The job does not belong to the caller. |
404 |
No job with that identifier. |
500 |
Internal server error. |
Example 202 Response:
{
"requestId": "e1f2a3b4-c5d6-4789-e0f1-a2b3c4d5e6f7"
}
GET /v1/health¶
Shallow liveness check.
Confirms the API is deployed and serving requests. Does not check the database or any other downstream dependency. Unauthenticated.
Response Body (200)¶
| Field | Type | Description |
|---|---|---|
status |
string | One of ok. |
timestamp |
string (date-time) |
Status Codes¶
| Status | Meaning |
|---|---|
200 |
The API is up. |