Skip to content

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/json with an upload_id: the file was first sent straight to storage through POST /v1/uploads (up to 15 MB). One upload makes at most one job: repeating the request returns that same job with 200, 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.

Processing Time After an Idle Period

After an hour with no traffic, the models shut down to save cost. The next job starts them again, which takes about 5 minutes for a transcription and about 7 for a summary or tags. The job is not lost: it stays queued or processing and finishes on its own, and later jobs run at normal speed. Keep polling for at least 20 minutes before treating a job as stuck (see the polling guidance and the FAQ).


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.