The MediaPitch API exposes endpoints for managing audio submissions, processing tasks, and consuming their results. All endpoints are versioned under the /api/v1 prefix and return JSON responses.

Authentication

Requests must include a valid API key. Provide the key as a Bearer token or the X-Api-Key header.

Authorization: Bearer YOUR_API_KEY

If the API key maps to a user, requests are executed on behalf of that user.

Rate limiting

API calls are limited to 60 requests per minute per user or IP address. Exceeding the limit results in HTTP 429 responses. The limit is enforced through Laravel's ThrottleRequests middleware and logged for monitoring.

Logging & metrics

Every request handled by the API is logged together with HTTP method, path, latency, authenticated user, and remote IP. A corresponding ApiRequestHandled event is dispatched so downstream systems can record metrics or forward the data to monitoring backends.

Error format

Errors are returned with the following structure:

{
  "message": "Human readable message",
  "errors": {
    "field": ["validation details"]
  }
}

Validation errors use HTTP status 422, authentication errors return 401, and authorization errors return 403.

Endpoints

Upload audio

POST /api/v1/audios

Upload an audio file that can later be attached to a submission. Files up to 25 MB are accepted. The currently supported file types are mp3, wav, m4a, aac, flac, and ogg.

Response 201 Created

{
  "data": {
    "id": 42,
    "name": "sales-call.wav",
    "url": "https://example.com/storage/audios/uploaded/sales-call.wav",
    "duration": 87.52,
    "size": 1854332
  }
}

Create submission

POST /api/v1/submissions

Create a submission for one or more downstream services (translate, transcribe, paraphrase, speaker diarization). A submission triggers task creation and immediately calls the LLM worker to begin processing.

Either audio_url or audio_id must be supplied.

Response 201 Created

{
  "data": {
    "submission": {
      "id": 73,
      "audio_name": "Q3 earnings call",
      "services": ["Transcribe", "Translate"],
      "status": "pending"
    },
    "task": {
      "id": 104,
      "status": "pending",
      "type": "Transcribe&Translate"
    }
  }
}

Get submission details

GET /api/v1/submissions/{submission}

Retrieve a submission together with its tasks and task results.

Response 200 OK

{
  "data": {
    "id": 73,
    "audio_name": "Q3 earnings call",
    "context": "Call with investor Q&A",
    "services": ["Transcribe", "Translate"],
    "tasks": [
      {
        "id": 104,
        "type": "Transcribe&Translate",
        "status": "done",
        "result": {
          "from": "completed",
          "payload": {
            "summary": "...",
            "chunks": [
              {"start": 0, "end": 17, "text": "..."}
            ]
          }
        }
      }
    ]
  }
}

List tasks

GET /api/v1/tasks

Return a paginated list of tasks that belong to the authenticated user. Optional filters may be supplied via query string parameters.

Response 200 OK

{
  "data": [
    {
      "id": 104,
      "type": "Transcribe&Translate",
      "status": "done",
      "created_at": "2024-04-06T12:34:10Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 2
  }
}

Submit task results

POST /api/v1/tasks/{task}/results

Attach processing output to a task. This endpoint is typically called by background workers when a job finishes. When status becomes completed, the user is notified, credits are updated, and a completion email is sent automatically.

Response 200 OK

{
  "data": {
    "task_id": 104,
    "status": "done"
  }
}

Examples

Download ready-to-run HTTPie examples that demonstrate the requests above.