Upload & Transcribe

Upload media to Trint for transcription, either directly or asynchronously from a URL you host.

There are two ways to get media into Trint, both authenticated with Basic Authentication using your API key ID and secret:

Direct upload — send the file as the request body and get a transcript ID back straight away. Simplest to implement, and the right choice for occasional or interactive uploads.
Asynchronous ingest — give Trint a URL to fetch the media from, and receive webhook callbacks as it progresses. Better for large files and for queuing many uploads at once, at the cost of needing an endpoint that can receive callbacks.

Direct upload

Upload media files directly to Trint to start transcription. Send the file as the request body and provide a filename query parameter so Trint can detect the media type.

Choosing a language

Pass a supported language code via the language query parameter. If omitted, Trint defaults to English.

Upload and Transcribe

posthttps://upload.trint.com/

Upload media files directly to Trint for immediate transcription

Query parameters

languagestringoptional

Language to transcribe

filenamestringrequired

The name of the file being uploaded

userstringoptional

The username to attach the uploaded file to. If the parameter is not specified it defaults to the user associated with the API key.

metadatastringoptional

Metadata to be included in the callback event

detect-speaker-changebooleanoptional

Automatically split paragraphs based on change of speaker. If the parameter is not specified it default to true.

folder-idstringoptional

Id of the folder you would like to upload to directly

workspace-idstringoptional

ID of the workspace/shared drive you'd like to upload to

custom-dictionarybooleanoptional

Use the Vocab Builder during the transcription of the file. If the parameter is not specified it default to true.

Headers

authorizationstringrequired

API key authorization

content-typestringrequired

MIME type of the media being uploaded

Body parameters

RAW_BODYstring (binary)required

The media file to be transcribed

POST /

curl -X POST 'https://upload.trint.com/?filename=myfile.mp4&folder-id=ID' \
    -u "AK-12345ABCDE:this15SECRET_CXJK3ctglt6LOpYxRmZ" \
    -H 'content-type: video/mp4' \
    --data-binary @myfile.mp4

Response 200

200 response

{
  "trintId": "myTrintId"
}

200200

400400

402402

Polling for completion

Uploading returns a transcript ID immediately, but transcription happens asynchronously. Either poll the Transcripts API for the transcript's status, or register a webhook to be notified when it is ready.

Asynchronous ingest

Instead of transferring the bytes yourself, host the media somewhere Trint can reach and submit the sourceUrl. Trint fetches, transcodes and transcribes the file, reporting progress to a callbackUrl you provide. Large files transfer faster this way, you can queue many requests at once, and a transfer that fails mid-way can be retried without re-uploading anything.

Your callback URL is verified before anything is queued

Your endpoint must respond 200 OK to the initial ACTIVITY_STARTED event, or the ingest request is rejected outright. Make sure the URL is reachable and returns promptly before you submit.

Ingest events are not the same as transcript webhooks

Ingest events are specific to one operation and are sent to the callbackUrl on the request itself. They are separate from the account-level webhooks you register for TRANSCRIPT_VERIFIED and TRANSCRIPT_NEW_VERSION — note that TRANSCRIPT_COMPLETE appears in both sets.

Queue a file for ingestion

Only sourceUrl and callbackUrl are required. Use metadata (up to 1KB) to carry your own correlation data through every callback, and folderId/sharedDriveId to place the result somewhere other than the account root. Store the operationToken from the response — it is what ties the callbacks back to this request.

Submit an ingest request

posthttps://upload.trint.com/ingest

Accepts a source URL and begins asynchronous media ingestion. Returns an operationToken that can be used to correlate webhook callbacks and track the operation.

Workflow

Callback verification — Trint sends an ACTIVITY_STARTED event to the callbackUrl to verify the endpoint responds with 200 OK. If the callback fails, the request is rejected.
202 Accepted — The API returns the operationToken.
Asynchronous processing — Media is downloaded, transcoded, and transcribed. Progress events are sent to the callbackUrl.

Webhook Events

The following events are sent to the callbackUrl as POST requests:

Event Type	Description
`ACTIVITY_STARTED`	Ingest operation has begun
`MEDIA_TRANSFER_COMPLETE`	Media successfully retrieved and stored
`MEDIA_TRANSFER_FAILED`	Media retrieval failed
`TRANSCRIPT_COMPLETE`	Transcription completed successfully
`TRANSCRIPT_FAILED`	Transcription processing failed

Each callback payload includes operationToken, eventType, and the metadata you provided in the original request.

Body parameters

sourceUrlstring (uri)required

Source URL from which Trint will retrieve the media file.

filenamestringoptional

Display name for the file in the Trint webapp. If omitted, an auto-generated UUID is used.

callbackUrlstring (uri)required

Required. Webhook URL for receiving progress notifications. Must use http or https protocol. The endpoint must respond with 200 OK to the initial ACTIVITY_STARTED verification event, or the ingest request will be rejected.

metadatastringoptional

Custom metadata string (max 1KB). Returned in all webhook callback payloads.

languagestringoptional

Language code for transcription (e.g., en-US, en-GB, fr, de).

folderIdstringoptional

ID of the folder to upload to. If the folder belongs to a workspace, sharedDriveId must also be provided.

sharedDriveIdstringoptional

ID of the workspace (shared drive) to upload to. Cannot be an archived workspace.

POST /ingest

curl --request POST \  --url 'https://upload.trint.com/ingest' \
  --header 'Authorization: Basic YOUR_BASE64_KEY_ID_AND_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{}'

Response 202

202 response

{
  "operationToken": "550e8400-e29b-41d4-a716-446655440000"
}

202Accepted — the ingest operation has been queued for processing.

400Bad Request — invalid or missing parameters.

401Unauthorized — missing or invalid credentials.

403Forbidden — credentials are valid but not permitted. Only API Key v2 and Bearer tokens are accepted.

429Too Many Requests — rate limit exceeded.

503Service Unavailable — the ingest service is temporarily disabled.

Check in-flight uploads

Reconcile what Trint thinks is in flight, either as a cursor-paged list or as aggregate counts per status.

Get upload status

gethttps://upload.trint.com/ingest

Returns a paginated list of uploads with their current status, or an aggregate summary of upload counts per status group.

Views

List view (default) — Returns individual upload records with pagination.
Summary view (?view=summary) — Returns aggregate counts per status: PENDING, IMPORTING, PROCESSING, READY, FAILED.

Rate Limiting

When the rate limit is exceeded, the endpoint returns a cached response from the most recent successful request with the same query parameters, rather than a 429 error. This ensures clients always receive data during high-frequency polling.

Query parameters

viewstringoptional

Set to summary to receive aggregate counts instead of the full list.

Allowed: summary

operationTokenstringoptional

Filter by a specific operation token.

statusarray of stringoptional

Comma-separated list of statuses to filter by. Valid values: PENDING, IMPORTING, PROCESSING, READY, FAILED.

Allowed: PENDING, IMPORTING, PROCESSING, READY, FAILED

userIdstringoptional

Filter uploads by a specific user. Only available to admin or workspace owner roles.

limitintegeroptional

Number of results per page.

cursorstringoptional

Base64-encoded cursor for fetching the next page. Use the nextCursor value from a previous response.

createdAfterstring (date-time)optional

Return only uploads created after this date (ISO 8601).

createdBeforestring (date-time)optional

Return only uploads created before this date (ISO 8601).

GET /ingest

curl --request GET \  --url 'https://upload.trint.com/ingest' \
  --header 'Authorization: Basic YOUR_BASE64_KEY_ID_AND_SECRET'

Response 200

200 response

{
  "uploads": [
    {
      "operationToken": "550e8400-e29b-41d4-a716-446655440000",
      "trintId": "abc123def456",
      "status": "READY",
      "filename": "Interview-2024.mp4",
      "language": "en-US",
      "createdAt": "2024-06-15T10:30:00.000Z",
      "updatedAt": "2024-06-15T10:35:00.000Z",
      "completedAt": "2024-06-15T10:35:00.000Z",
      "errorCode": null,
      "errorMessage": null
    },
    {
      "operationToken": "661f9511-f3ac-52e5-b827-557766551111",
      "status": "PROCESSING",
      "filename": "Meeting.wav",
      "language": "en-GB",
      "createdAt": "2024-06-15T11:00:00.000Z",
      "updatedAt": "2024-06-15T11:01:00.000Z",
      "completedAt": null,
      "errorCode": null,
      "errorMessage": null
    }
  ],
  "pagination": {
    "nextCursor": "eyJjcmVhdGVkIjoiMjAyNC0wNi0xNVQxMTowMDowMC4wMDBaIiwiaWQiOiI2NjFmOTUxMSJ9",
    "hasMore": true
  }
}

200Success — returns either a list of uploads or a summary, depending on the view parameter.

400Bad Request — invalid query parameters.

401Unauthorized — missing or invalid credentials.

403Forbidden — attempt to filter by another user without admin privileges.