Api

API Reference

HTTP contract for creating and reading transcript jobs.

Production requests use IAM SigV4. The local sandbox exposes the same routes without authentication.

Create Transcript Job

POST /v1/transcripts
Authorization: AWS SigV4
Content-Type: application/json

{
  "callback": {
    "url": "https://your-service.example.com/webhook",
    "events": ["completed", "failed"]
  },
  "metadata": {
    "workspaceId": "ws-abc123",
    "interactionId": "int-xyz789"
  },
  "idempotencyKey": "ws-abc123-int-xyz789",
  "payload": {
    "input": {
      "audio_url": "https://bucket.s3.eu-central-1.amazonaws.com/audio.wav?X-Amz-..."
    },
    "config": {
      "language": "es",
      "keyterms": ["Decathlon", "Pluxee"],
      "context": "Customer support call for Decathlon",
      "context_model": "medium"
    }
  }
}

Accepted jobs return 202 Accepted:

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

Request Fields

Field	Required	Description
`callback.url`	Yes	HTTPS endpoint that receives completion and failure notifications. Production callbacks are SigV4 signed.
`callback.events`	Yes	Events to emit. Supported values are `completed`, `failed`, `transcribed`, `contextualized`, and `profiled`.
`metadata`	Yes	Opaque caller metadata passed through to status responses and callbacks.
`idempotencyKey`	Yes	Caller-provided deduplication key, up to 256 characters.
`payload.input.audio_url`	Yes	Pre-signed HTTPS URL to the source audio. It must remain valid long enough for the pipeline to fetch it.
`payload.config.language`	No	ISO 639-1 language code. If omitted, the provider may auto-detect.
`payload.config.keyterms`	No	Terms used to bias transcription. Maximum 1000 terms, up to 10 words each.
`payload.config.context`	No	Natural language context. When present, it enables the Bedrock contextualization step.
`payload.config.context_model`	No	LLM quality tier for contextualization: `fast`, `medium`, or `high`. Defaults to `medium`.

Get Job Status

GET /v1/transcripts/{jobId}
Authorization: AWS SigV4

Completed jobs include the canonical result:

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "metadata": { "workspaceId": "ws-abc123" },
  "result": { "schema_type": "customer-interaction" }
}

Status Lifecycle

Status	Description
`pending`	Job accepted, not yet started.
`processing`	Transcription is running.
`transcribed`	ElevenLabs completed and the raw transcript is available for post-processing.
`contextualized`	Optional Bedrock correction completed.
`profiled`	Participant roles and actor types were resolved.
`completed`	Final `CustomerInteraction@v1.0` was validated and stored.
`failed`	The pipeline stopped and `error` contains failure details.

Health Check

GET /v1/health

{ "status": "healthy" }

Callbacks include the original metadata and the terminal job state. Consumers must treat callbacks as notifications and use the status endpoint as the source of truth when they need to reconcile state.

Processing Pipeline