API Documentation

Overview

The Rumlin API provides programmatic access to upload audio files for transcription and analysis. All endpoints return JSON responses and use standard HTTP status codes.

API access is included on our Growth and Enterprise plans. If your organisation is on Starter or is trialling Rumlin, upgrade to Growth or Enterprise to use the API and Zapier integrations.

Base URL

https://rumlin.io

What You Can Do

• Upload audio files for transcription and analysis
• Assign uploads to specific spaces and agents

Authentication

The Rumlin API supports Bearer token authentication using API keys. You can obtain an API key from your organisation settings in the Rumlin dashboard.

API Key Authentication

Include your API key in the Authorization header of your requests:

curl -X POST https://rumlin.io/api/upload \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "[email protected]"

Security Best Practices

• Never expose your API key in client-side code
• Use HTTPS for all API requests
• Rotate your API keys regularly
• Monitor API key usage in your dashboard

Upload Endpoint

POST /api/upload

Upload Audio File

Upload one or more audio files for transcription and analysis. Files are processed asynchronously.

Request Parameters

Parameter	Type	Required	Description
`files`	File(s)	Required	Audio file(s) to upload. Supported formats: MP3, WAV, MP4, M4A, FLAC
`folder_id` (alias: `space_id`)	String	Optional	UUID of the folder to assign the transcript to
`agent_id`	String	Optional	UUID of the agent to assign the transcript to
`scorecard_ids` (alias: `scorecard_id`)	String	Optional	UUID of the scorecard to score this call with. One scorecard per call: send a single value (more than one returns `400` `TOO_MANY_SCORECARDS`). Send `none` to leave the call unscored. If omitted, the folder's default scorecard is used, if it has one. Scoring runs after transcription and only if auto-scoring is switched on for your organisation in Settings.

Example Request

curl -X POST https://rumlin.io/api/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@meeting_recording.mp3" \
  -F "folder_id=123e4567-e89b-12d3-a456-426614174000" \
  -F "scorecard_ids=789e0123-e89b-12d3-a456-426614174002"
                    

Example Response

{
  "message": "1 files queued for processing",
  "results": [
    {
      "filename": "meeting_recording.mp3",
      "queue_id": "456e7890-e89b-12d3-a456-426614174001",
      "status": "queued",
      "source": "API",
      "scorecard_id": "789e0123-e89b-12d3-a456-426614174002",
      "estimated_duration_minutes": 12
    }
  ]
}
                        

Error Handling

The API uses standard HTTP status codes to indicate success or failure. Error responses include a JSON object with an error message.

HTTP Status Codes

Status Code	Description
`200`	OK - Request successful
`400`	Bad Request - Invalid request parameters. Includes `TOO_MANY_SCORECARDS` (more than one scorecard sent) and an unknown, inactive or foreign `scorecard_ids` value; nothing is uploaded in either case
`401`	Unauthorized - Invalid or missing API key
`402`	Payment Required - Your plan doesn't include API uploads, or your trial or subscription has ended (`"code": "feature_locked"`)
`404`	Not Found - Resource not found
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Server error

Error Response Format

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
                