Skip to content
OnCoreDocs
Transcriber Tests

GEThttps://core-api.heysadie.ai/turn-flags/calls/{callId}/lines

callId success data messageIndex role text audio startSeconds endSeconds flaggable notFlaggableReason flag id kind recording channels durationSeconds liveTranscriber name metadata timestamp version path error code message details field

List a call's lines for flagging

Every caller and assistant line of a call, by `messageIndex`, with whether each can be flagged, why not, and the turn already on it. Call it to render a call transcript in flagging mode. - Offer a flag action on lines with `flaggable: true` and send their `messageIndex` to POST /turn-flags. - `flag` marks a line already flagged, or sampled as a control; edit it with PATCH /turn-flags/:id. - `liveTranscriber` is the transcriber the call ran on, whose text a flag scores as production. When it or `recording` is null, no line is flaggable. - To play a line, fetch GET /turn-flags/calls/:callId/recording-url. Errors: 404 RESOURCE_NOT_FOUND when the call is not in the organization.

Try it in the API Explorer

Example request

Terminal
curl "https://core-api.heysadie.ai/turn-flags/calls/CALL_ID/lines" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Authentication

Authenticate with an API key in the Authorization header using the ApiKey scheme. See Authentication for how keys work and where to get them.

Authorizationstringrequired

API key in the ApiKey scheme: ApiKey YOUR_API_KEY. Tenant keys authorize their own tenant; organization keys can act on any tenant in the organization.

X-Tenant-Idstring (uuid)optional

Required when authenticating with an organization key: it selects the tenant the request acts on. Omit with tenant keys.

Request

Path parameters

callIdstringrequired

A call of the organization

Responses

200The call's lines, recording and live transcriber
successbooleanrequired

true on every 2xx

dataobjectoptional

The result

Show 3 child properties
dataobject[]required

Every caller and assistant line of the call's messages, by index. Empty once retention scrubs them (90 days)

Show 7 item properties
messageIndexstring (integer) | integerrequired

Index in the call's messages. Send it to POST /turn-flags

roleenumrequired

user: the caller. bot: the assistant. Only caller lines can be flagged

Allowed values:"user""bot"
textstringrequired

What the live transcriber wrote, or what the assistant said

audioobject | nullrequired

The line's place in the recording. Null when the call stored none for it

Show 2 child properties
startSecondsnumberrequired

Where the line starts, in seconds from the recording start

endSecondsnumberrequired

Where the line ends, in seconds from the recording start

flaggablebooleanrequired

Whether POST /turn-flags accepts this line

notFlaggableReasonenum | nullrequired

Null when flaggable. Why a line cannot be flagged, the first that holds of: not_caller_line (an assistant line), no_recording (the call has no recording), transcriber_unknown (the call records no transcriber and its cost breakdown names none uniquely, so there is no live transcriber to score against), no_audio_bounds (the line has no start and end in the recording)

Allowed values:"not_caller_line""no_audio_bounds""no_recording""transcriber_unknown"
flagobject | nullrequired

The live turn on the line: its flag, else a control sampled on it. Null when none

Show 2 child properties
idstringrequired

The turn's id, for PATCH or DELETE /turn-flags/:id

kindenumrequired

flagged: a person flagged the line. control: the system sampled it as a control for a flag on the same call

Allowed values:"flagged""control"
recordingobject | nullrequired

The call's recording. Null when it has none, and then no line is flaggable

Show 2 child properties
channelsenumrequired

stereo: agent left, caller right. mono: both mixed

Allowed values:"stereo""mono"
durationSecondsnumber | nullrequired

The call's length in seconds. Null when unknown

liveTranscriberobject | nullrequired

The transcriber the call ran on: the one recorded on the call, else the only live catalogue row whose name equals the STT name in the call's cost breakdown. A flag scores this transcriber's stored text as production. Null when neither names one, and then no line is flaggable

Show 2 child properties
idstringrequired

Transcriber id, as GET /transcribers lists it

namestringrequired

The transcriber's display name

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

400VALIDATION_ERROR: a path id, query parameter or body field broke a rule; `details` lists each `field` and its `message`. A body with a missing field or a JSON type the schema does not allow answers 400 with code INTERNAL_SERVER_ERROR and no `details` instead, so branch on the status
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 3 child properties
codeenumrequired

A parameter or body field broke a rule

Allowed values:"VALIDATION_ERROR"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

detailsobject[]optional

One entry per field that failed

Show 2 item properties
fieldstringrequired

The offending field

messagestringrequired

The rule it broke

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

401UNAUTHORIZED: no valid credentials, or a dashboard token that names no organization. Send `Authorization: ApiKey <organization API key>`
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 2 child properties
codeenumrequired

No valid credentials

Allowed values:"UNAUTHORIZED"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

403ORG_SCOPE_REQUIRED: transcriber testing is an organization feature. Use an organization API key without `X-Tenant-Id`, or a dashboard token scoped to the organization. A tenant API key, an organization key sent with `X-Tenant-Id` for one of its tenants, or a token carrying a tenant gets this 403. FORBIDDEN: an organization key sent `X-Tenant-Id` for a tenant outside its organization
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 2 child properties
codeenumrequired

ORG_SCOPE_REQUIRED: the credentials carry a tenant scope. FORBIDDEN: an organization key sent `X-Tenant-Id` for a tenant outside its organization

Allowed values:"ORG_SCOPE_REQUIRED""FORBIDDEN"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

404RESOURCE_NOT_FOUND: an id in the path, query or body names nothing in the caller's organization. `message` names what, e.g. "Transcriber bank not found"
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 2 child properties
codeenumrequired

An id names nothing the caller can see

Allowed values:"RESOURCE_NOT_FOUND"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

500An unexpected server error
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 2 child properties
codeenumrequired

An unexpected server failure

Allowed values:"INTERNAL_SERVER_ERROR"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested