resources/media.ts

Source: sdks/typescript/packages/sdk/src/resources/media.ts. Back to the TypeScript SDK reference index.

note

This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.

Type alias MediaOperation

Operation a media is uploaded for, for example stt, ocr, image_generation or voice_live.

Definition: \| "stt" \| "tts" \| "ocr" \| "vision_understanding" \| "image_generation" \| "image_edit" \| "video_generation" \| "video_processing" \| "diarization" \| "document_extraction" \| "voice_live".

Interface MediaUpload

Input of MediaResource.upload: the file and its upload settings.

Fields:

Name	Type	Required	Description
file	Blob	yes	Content to upload, sent with filename (default file).
filename	string	no	Name of the uploaded file, sent with the multipart part (default file).
mime_type	string	no	Media type of the content, for example application/pdf or image/png.
operation	MediaOperation	no	Operation the media is meant for.
classification	"public" | "internal" | "confidential" | "restricted" | "secret"	no	Classification of the media: public, internal, confidential, restricted or secret.
dlp_mode	"detect" | "mask" | "tokenize" | "block"	no	DLP mode applied to the media: detect, mask, tokenize or block.
retention_days	number	no	Days a backup is kept before it can be deleted, 1 or more.

Class MediaResource

Multimodal. Media and multimodal processing: encrypted media storage and jobs for vision, image generation and edition, video processing and generation, speech to text, diarization, text to speech and multimodal DLP.

Resource

MediaResource.delete

delete(id: string, opts?: CallOptions)

Delete a media. Deletes the media and its stored content. Allowed for its creator, tenant_admin or security_officer (403 forbidden). A media under legal hold answers 409 legal_hold. Audited as media.delete.

Route: /v1/media/{media_id} (DELETE).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the media.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MediaResource.get

get(id: string, options: { includeContent?: boolean } & CallOptions = {})

Get a media. Returns the Multimodal Contract document of the media. With include_content=true the answer is {media, content_base64} with the decrypted content; this needs a clearance at least equal to the media classification (403 policy_denied) and is audited as media.read.

Route: /v1/media/{media_id} (GET).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the media.
options	{ includeContent?: boolean } & CallOptions	{}	no	Per call options (idempotency key, traceparent, headers, abort signal).

Raises: the typed errors of the transport (Errors).

MediaResource.list

list(params?: ListParams, opts?: CallOptions)

List the media. Tenant media (Multimodal Contract documents), keyset paginated with cursor, filtered by media_type and classification (400 invalid_request for an unknown value).

Route: /v1/media (GET).

Name	Type	Default	Required	Description
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MediaResource.upload

upload(input: MediaUpload | FormData, opts?: CallOptions)

Upload a media. Stores a media (201) from JSON {content_base64, mime_type, filename?, operation?, dlp_mode?, retention_days?, classification?} or multipart/form-data with a file part and the same fields. Any tenant principal may call it. Steps: 1. Size checked against the platform maximum (50 MiB unless configured; 413 media_too_large). 2. File scan by ClamAV and YARA-X (422 file_blocked, 503 file_scan_unavailable). 3. Text extraction and DLP with dlp_mode (default detect; block answers 422 dlp_blocked when personal data is found); the classification is raised accordingly. 4. The content is encrypted with a tenant key and stored. Returns the Multimodal Contract document.

Route: /v1/media (POST).

Name	Type	Default	Required	Description
input	MediaUpload | FormData		yes	A ready FormData, or a MediaUpload turned into one.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

Class MultimodalResource

Multimodal. Media and multimodal processing: encrypted media storage and jobs for vision, image generation and edition, video processing and generation, speech to text, diarization, text to speech and multimodal DLP.

Resource

Attributes:

Name	Type	Required	Description
body	{ status: "running" | "succeeded" | "failed" | "cancelled"; output?: Doc; error?: string; units?: Doc },	yes	Result of the job sent by completeJob: status, output, error and measured units.
id	string,	yes	Id of the job completed by completeJob.
opts	CallOptions,	no	Per call options of completeJob.

MultimodalResource.completeJob

completeJob(id: string, body: { status: "running" | "succeeded" | "failed" | "cancelled"; output?: Doc; error?: string; units?: Doc }, opts?: CallOptions)

Report the result of a queued job. Called by GPU workers (agent or service identities) to report a queued job result: status running, succeeded, failed or cancelled (else 400 invalid_request), with output, error and measured units; the quota reservation is committed or released. A finished job answers 409 conflict. Needs agent or tenant_admin. 404 not_found.

Route: /v1/multimodal/jobs/{job_id}/complete (POST).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the job.
body	{ status: "running" | "succeeded" | "failed" | "cancelled"; output?: Doc; error?: string; units?: Doc }		yes	Status, output, error and measured units of the job.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MultimodalResource.diarize

diarize(body: Doc, opts?: CallOptions)

Diarize an audio. Starts a diarization job (who spoke when) on an audio media or inline audio (201, the job). Only min_speakers and max_speakers apply here (word_timestamps answers 422 parameter_unsupported); min_speakers must not exceed max_speakers (422 parameter_invalid); an option the configured provider cannot honour answers 422 parameter_unsupported. Needs tenant_admin, developer or agent.

Route: /v1/multimodal/diarize (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Audio input and speaker bounds.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MultimodalResource.dlp

dlp(body: Doc, opts?: CallOptions)

Run the DLP on a text or a media. Inspects text, the extracted text of a stored media, or inline content (scanned first), with the tenant DLP rules. Returns source, extracted_text_chars, the processed text, findings, action and classification. Nothing is stored. Any tenant principal may call it. Audited as multimodal.dlp.

Route: /v1/multimodal/dlp (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Text, stored media or inline content, and the DLP mode.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MultimodalResource.editImage

editImage(body: Doc, opts?: CallOptions)

Edit an image. Starts an image edition job from an image media or inline image and a prompt (201, the job). The input must be an image (422 unsupported_media). Needs tenant_admin, developer or agent.

Route: /v1/multimodal/images/edit (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Input image, prompt, number of images, size and model.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MultimodalResource.generateImage

generateImage(body: Doc, opts?: CallOptions)

Generate images. Starts an image generation job (201, the job). The prompt is inspected by the DLP in block mode first: personal data answers 422 dlp_blocked. Usage is counted per image. Needs tenant_admin, developer or agent.

Route: /v1/multimodal/images/generate (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Prompt, number of images, size and model.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MultimodalResource.generateVideo

generateVideo(body: Doc, opts?: CallOptions)

Generate a video. Starts a video generation job and answers 202 with the job; follow it with GET /v1/multimodal/jobs/{job_id}. Usage is counted in video seconds. Needs tenant_admin, developer or agent.

Route: /v1/multimodal/video/generate (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Prompt, duration, size and model.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MultimodalResource.getJob

getJob(id: string, opts?: CallOptions)

Get a multimodal job. Returns the job: operation, status, input parameters, output, error, adapter, units and cost. 404 not_found.

Route: /v1/multimodal/jobs/{job_id} (GET).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the job.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MultimodalResource.listJobs

listJobs(params?: ListParams, opts?: CallOptions)

List the multimodal jobs. Jobs of the tenant, newest first, paginated with cursor, optionally filtered by status and operation.

Route: /v1/multimodal/jobs (GET).

Name	Type	Default	Required	Description
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MultimodalResource.processVideo

processVideo(body: Doc, opts?: CallOptions)

Process a video. Extracts frames and/or the audio track of a video media or inline video (201, the job; queued when ffmpeg is not available). operations accepts frames and audio only (400 invalid_request). Needs tenant_admin, developer or agent.

Route: /v1/multimodal/video/process (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Input video, operations, frame rate and audio sample rate.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MultimodalResource.stt

stt(body: Doc, opts?: CallOptions)

Transcribe speech to text. Starts a speech to text job on an audio media or inline audio (201, the job). The transcript goes through the DLP with dlp_mode. Only word_timestamps applies here (speaker bounds answer 422 parameter_unsupported). Usage is counted in audio seconds (duration_seconds, or read from a WAV header). Needs tenant_admin, developer or agent.

Route: /v1/multimodal/stt (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Audio input, language, model, DLP mode and options.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MultimodalResource.tts

tts(body: Doc, opts?: CallOptions)

Synthesize speech from text. Starts a text to speech job (201, the job). The text is inspected by the DLP with dlp_mode (default block: personal data answers 422 dlp_blocked; mask speaks the masked text). Usage is counted in characters. Needs tenant_admin, developer or agent.

Route: /v1/multimodal/tts (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Text, voice, model and DLP mode.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MultimodalResource.vision

vision(body: Doc, opts?: CallOptions)

Understand an image. Starts a vision understanding job on an image media or inline image with a prompt (201, the job). The answer goes through the DLP with dlp_mode. detail answers 422 parameter_unsupported when the configured provider cannot honour it; a non image input answers 422 unsupported_media. Needs tenant_admin, developer or agent.

Route: /v1/multimodal/vision (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Input image, prompt, model, DLP mode and detail level.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

Interface RealtimeSessionView

Realtime session view returned by GET /v1/realtime/sessions/{id} and POST .../end.

Doc

Fields:

Name	Type	Required	Description
id	string	yes	Id of the session.
room	string	yes	LiveKit room name (1 to 128 letters, digits, ., _, -). Default: derived from the tenant and the session.
identity	string	yes	Participant identity in the room.
pipeline	"echo" | "stt" | string	yes	echo (default) or stt.
config	Doc	yes	Configuration of the session.
status	string	yes	State of the session.
audio_seconds	number | string	yes	Seconds of audio processed.
input_tokens	number	yes	Input tokens used by the session.
output_tokens	number	yes	Output tokens used by the session.
usage	Doc | null	yes	Usage counters added to the budget consumption, for example input_tokens, output_tokens.
created_by	string	yes	Principal that created the session.
created_at	string	yes	Time the session was created.
ended_at	string | null	yes	Time the session ended, null while it is open.

Interface RealtimeSession

POST /v1/realtime/sessions response: the view plus connection material.

RealtimeSessionView

Fields:

Name	Type	Required	Description
session_id	string	yes	Id of the session.
ws_url	string	yes	Relative path /v1/realtime/ws/{id}?token=<ws_token>.
ws_token	string	yes	Single use token of the WebSocket; createToken gives a new one before a reconnection.
livekit	{ url: string; token: string; room: string; configured: boolean }	yes	LiveKit URL, token and room, and whether LiveKit is configured.

Interface RealtimeConsent

Body of POST /v1/realtime/sessions/{id}/consents.

Fields:

Name	Type	Required	Description
purpose	string	yes	Use of the target. Default backup.
retention_days	number	yes	Days a backup is kept before it can be deleted, 1 or more.
method	string	no	Name of the method, for example basic, token or none.
participant_identity	string	no	Identity of the participant (1 to 128 letters, digits, ., _, :, @, -). Default: the participant of the session.
recording_allowed	boolean	no	Whether the audio may be recorded. Default false.
transcription_allowed	boolean	no	Whether the speech may be transcribed and stored. Default false.

Class RealtimeResource

Realtime voice. Realtime voice sessions: a LiveKit room token and a WebSocket event protocol to stream audio to an agent, with participant consent, turns, DLP filtered transcripts, optional recordings and metering.

Resource

RealtimeResource.createSession

createSession(body: { pipeline?: "echo" | "stt"; room?: string; ttl_seconds?: number; config?: Doc; agent_id?: string; on_behalf_of?: string } = {}, opts?: CallOptions)

Open a realtime session. Opens a session (201) and returns it with session_id, livekit (url, token, room, configured) and the WebSocket access (ws_url, ws_token, ws_token_expires_at). Needs tenant_admin, developer or agent. Checks: pipeline is echo or stt (400 invalid_request); config.vad and config.dlp_mode are valid (422 parameter_invalid); an agent caller acts for on_behalf_of, a user may only open a session for itself (403 identity_mismatch); LiveKit credentials are configured; the policy realtime.session.create is evaluated. The room defaults to a name derived from the tenant and the session. Audited as realtime.session.create.

Route: /v1/realtime/sessions (POST).

Name	Type	Default	Required	Description
body	{ pipeline?: "echo" | "stt"; room?: string; ttl_seconds?: number; config?: Doc; agent_id?: string; on_behalf_of?: string }	{}	no	Room, pipeline, token lifetime, configuration, agent and user acted for.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RealtimeResource.createToken

createToken(id: string, opts?: CallOptions)

Get a new WebSocket token. New single use WebSocket token for an open session (reconnection), read under RLS: ws_url, ws_token, ws_token_expires_at. 409 session_ended; 404 not_found. Needs tenant_admin, developer or agent. Audited as realtime.session.token.

Route: /v1/realtime/sessions/{session_id}/token (POST).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the realtime session.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RealtimeResource.endSession

endSession(id: string, opts?: CallOptions)

End a realtime session. Ends the session and records its usage event (voice_live: audio seconds, input and output tokens, measured cost). Ending a session already ended returns it unchanged. Needs tenant_admin, developer or agent. Audited as realtime.session.end.

Route: /v1/realtime/sessions/{session_id}/end (POST).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the realtime session.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RealtimeResource.getSession

getSession(id: string, opts?: CallOptions)

Get a realtime session. Returns the session: room, identities, agent, pipeline, configuration, status, audio seconds, tokens and usage. 404 not_found.

Route: /v1/realtime/sessions/{session_id} (GET).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the realtime session.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RealtimeResource.listConsents

listConsents(id: string, opts?: CallOptions)

List the consents of a session. Consents recorded for the session, in capture order, with their revocation when revoked. One page only.

Route: /v1/realtime/sessions/{session_id}/consents (GET).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the realtime session.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RealtimeResource.recordConsent

recordConsent(id: string, body: RealtimeConsent, opts?: CallOptions)

Record a participant consent. Consent of one participant (purpose, recording, transcription, retention, method), captured by the caller (201). The participant defaults to the participant of the session. The method must be verbal, click, written or api (422 parameter_invalid); the session must not be ended (409 session_ended); the policy realtime.consent.record is evaluated. Needs tenant_admin, developer or agent. Audited as realtime.consent.record.

Route: /v1/realtime/sessions/{session_id}/consents (POST).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the realtime session.
body	RealtimeConsent		yes	The consent of the participant.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RealtimeResource.revokeConsent

revokeConsent(id: string, consentId: string, opts?: CallOptions)

Revoke a consent. Revocation takes effect on the next audio event: transcription and recording are refused again. A consent already revoked or unknown answers 404 not_found. Needs tenant_admin, developer or agent. Audited as realtime.consent.revoke.

Route: /v1/realtime/sessions/{session_id}/consents/{consent_id}/revoke (POST).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the realtime session.
consentId	string		yes	Identifier (UUID) of the consent.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RealtimeResource.transcripts

transcripts(id: string, opts?: CallOptions)

List the transcripts of a session. Stored transcripts, already filtered by the DLP (the raw transcript is never stored), with turn, consent, participant, DLP findings and expiry. Needs tenant_admin, developer, auditor or security_officer.

Route: /v1/realtime/sessions/{session_id}/transcripts (GET).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the realtime session.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RealtimeResource.turns

turns(id: string, opts?: CallOptions)

List the turns of a session. Turns with the participant, the user, the agent, the trace id, the status (a barge-in records cancelled) and the measured latency, in order. One page only.

Route: /v1/realtime/sessions/{session_id}/turns (GET).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the realtime session.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

Class EvaluationsResource

Evaluation and red team. Quality of the AI systems of the tenant: evaluation suites, evaluation runs, quality gates before promotion, A/B comparisons against a baseline and red team runs.

Resource

EvaluationsResource.checkGate

checkGate(body: Doc, opts?: CallOptions)

Check the quality gate of a target. Checks that the latest finished run of every blocking suite of the target (for target.version when given, and limited to suite_ids when given) has passed. With run_missing: true, a suite without any run is run now; otherwise it counts as missing.

Route: /v1/evaluations/gates/check (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Target, optional suites and whether to run missing suites.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

EvaluationsResource.createComparison

createComparison(body: Doc, opts?: CallOptions)

Compare a candidate with a baseline. Runs one suite twice, on the baseline and on the candidate (each {type, ref, version}, type model by default, agent or prompt), and stores both runs, the per metric deltas and the verdict. Deltas are oriented by the comparator of each metric (gte: higher is better, lte: lower is better).

Route: /v1/evaluations/comparisons (POST).

Name	Type	Default	Required	Description
body	Doc		yes	JSON object: suite_id, baseline, candidate, optional tolerance (0 to 1, default 0) and outputs ({"baseline": [...], "candidate": [...]}, precomputed outputs per case).
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

EvaluationsResource.createRun

createRun(body: Doc, opts?: CallOptions)

Run an evaluation suite. Runs a suite now and returns the finished run (201). Needs tenant_admin, developer, security_officer or ai_governance_officer or agent.

Route: /v1/evaluations/runs (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Suite, optional target, precomputed outputs and trigger.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

EvaluationsResource.createSuite

createSuite(body: Doc, opts?: CallOptions)

Create an evaluation suite. Creates a suite. Needs tenant_admin, developer, security_officer or ai_governance_officer. Errors 400 invalid_request: target type not in model, agent, prompt, rag_pipeline, skill or tool, unknown engine or kind, comparator other than gte or lte, or, for the custom engine, a metric other than exact_match, contains, not_contains, json_valid, faithfulness, latency or refusal. A name already used answers 409 conflict. The dataset gets its size and a SHA-256 digest of the cases. Writes the audit event evaluation.suite.create.

Route: /v1/evaluations/suites (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Name, target, engine, kind, dataset, cases, metrics and gate options.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

EvaluationsResource.getComparison

getComparison(id: string, opts?: CallOptions)

Get an A/B comparison. Returns one comparison. Needs tenant_admin, developer, security_officer, auditor, viewer or finops. Answers 404 comparison_not_found.

Route: /v1/evaluations/comparisons/{comparison_id} (GET).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the comparison.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

EvaluationsResource.getRun

getRun(id: string, opts?: CallOptions)

Get an evaluation run. Returns one evaluation run with its results per metric and per case. Open to any member of the tenant. Answers 404 not_found.

Route: /v1/evaluations/runs/{run_id} (GET).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the evaluation run.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

EvaluationsResource.getSuite

getSuite(id: string, opts?: CallOptions)

Get an evaluation suite. Returns one suite with its full list of cases and run_on_promotion. Open to any member of the tenant. Answers 404 not_found.

Route: /v1/evaluations/suites/{suite_id} (GET).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the suite.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

EvaluationsResource.listComparisons

listComparisons(query: { suite_id?: string } = {}, opts?: CallOptions)

List the A/B comparisons. Lists the comparisons of the tenant, newest first, at most 200, optionally for one suite. Each gives baseline, candidate, both run ids, per metric deltas, tolerance and verdict. Needs tenant_admin, developer, security_officer, auditor, viewer or finops.

Route: /v1/evaluations/comparisons (GET).

Name	Type	Default	Required	Description
query	{ suite_id?: string }	{}	no	Query string parameters of the route.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

EvaluationsResource.listRuns

listRuns(params?: ListParams, opts?: CallOptions)

List the evaluation runs. Lists the evaluation runs of the tenant, newest identifier first, paginated, optionally filtered by suite and status. Each item follows the Evaluation Contract (target, engine, dataset, metrics, results, status, cost) with run_id, suite_id, trigger, case_results and error. Open to any member of the tenant.

Route: /v1/evaluations/runs (GET).

Name	Type	Default	Required	Description
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

EvaluationsResource.listSuites

listSuites(params?: ListParams, opts?: CallOptions)

List the evaluation suites. Lists the suites of the tenant ordered by name, paginated, as Evaluation Contract documents; cases gives the number of cases. Open to any member of the tenant.

Route: /v1/evaluations/suites (GET).

Name	Type	Default	Required	Description
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

Class RedteamResource

Evaluation and red team. Quality of the AI systems of the tenant: evaluation suites, evaluation runs, quality gates before promotion, A/B comparisons against a baseline and red team runs.

Resource

RedteamResource.createRun

createRun(body: Doc, opts?: CallOptions)

Run a red team campaign. Sends adversarial probes to the target and stores the findings. Needs tenant_admin, developer, security_officer or ai_governance_officer.

Route: /v1/redteam/runs (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Target, engine, probes and accepted attack success rate.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RedteamResource.getRun

getRun(id: string, opts?: CallOptions)

Get a red team run. Returns one red team run: target, engine, probes, status, summary (total, vulnerable, attack success rate, threshold, per category) and findings. Open to any member of the tenant. Answers 404 not_found.

Route: /v1/redteam/runs/{run_id} (GET).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the red team run.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RedteamResource.listRuns

listRuns(params?: ListParams, opts?: CallOptions)

List the red team runs. Lists the red team runs of the tenant, newest identifier first, paginated, and probes: the builtin probes (id and category), the garak probe families and whether garak is installed. Open to any member of the tenant.

Route: /v1/redteam/runs (GET).

Name	Type	Default	Required	Description
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

Class AuditResource

Audit events (/v1/audit): listing, application events, hash chain checks, WORM export and correlations.

Resource

AuditResource.correlations

correlations(query?: Query, opts?: CallOptions)

Correlate events by trace, run or session. With trace_id, run_id or session_id (the first given wins), returns everything that shares that key: audit_events, LLM usage_events, runs, telemetry spans, multimodal_jobs (up to 1000 of each, 200 for runs and jobs), the trace_ids met and counts.

Route: /v1/audit/correlations (GET).

Name	Type	Default	Required	Description
query	Query		no	Query string parameters of the route.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

AuditResource.export

export(body: Doc = {}, opts?: CallOptions)

Export the audit trail. Writes the events of the period (bounds included) to write once storage, as NDJSON or CSV, with a manifest. Needs auditor, security_officer or tenant_admin.

Route: /v1/audit/export (POST).

Name	Type	Default	Required	Description
body	Doc	{}	no	Period, retention and format of the export. An empty body exports everything as NDJSON kept 365 days.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

AuditResource.get

get(id: string, opts?: CallOptions)

Get an audit event. Returns one audit event with its sequence, hashes, actor, resource, decision and evidence. Needs auditor, security_officer or tenant_admin. The read is recorded in the evidence access log. Answers 404 not_found.

Route: /v1/audit/events/{event_id} (GET).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the audit event.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

AuditResource.iterate

iterate(params?: ListParams, opts?: CallOptions)

Search the audit events. Searches the audit events of the tenant, newest first (highest sequence first), paginated. All filters combine. Needs auditor, security_officer or tenant_admin. The search itself is recorded in the evidence access log (who, which query, how many results).

Route: /v1/audit/events (GET).

Name	Type	Default	Required	Description
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

AuditResource.list

list(params?: ListParams, opts?: CallOptions)

Search the audit events. Searches the audit events of the tenant, newest first (highest sequence first), paginated. All filters combine. Needs auditor, security_officer or tenant_admin. The search itself is recorded in the evidence access log (who, which query, how many results).

Route: /v1/audit/events (GET).

Name	Type	Default	Required	Description
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

AuditResource.query

query(params?: ListParams, opts?: CallOptions)

Search the audit events. Searches the audit events of the tenant, newest first (highest sequence first), paginated. All filters combine. Needs auditor, security_officer or tenant_admin. The search itself is recorded in the evidence access log (who, which query, how many results).

Route: /v1/audit/events (GET).

Name	Type	Default	Required	Description
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

AuditResource.record

async record(body: AuditRecord, opts?: CallOptions): Promise<AuditRecorded>

Record an application audit event. Appends an application event to the tenant hash chain. The actor comes from the authentication; the sequence, the hashes and occurred_at from the server; the client details are kept under evidence.details.attributes, next to stream: sdk. The event is sealed and exported to the outbox and the SIEM like the platform events.

Route: /v1/audit/events (POST).

Name	Type	Default	Required	Description
body	AuditRecord		yes	The application event. Fields other than those of the schema are refused.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Returns: Promise<AuditRecorded>. A AuditRecorded: Receipt of POST /v1/audit/events.

Raises: EaiError, the typed errors of the transport (Errors).

AuditResource.verify

verify(query?: Query, opts?: CallOptions)

Verify the audit chain. Recomputes the hash chain of the tenant from the first event and returns tenant_id, valid, count, last_hash, broken_at, reason and verified_at. When the chain is broken, broken_at is the sequence of the first faulty event and reason says why: sequence gap, prev_hash mismatch or hash mismatch. Needs auditor, security_officer or tenant_admin. The verification is recorded in the evidence access log.

Route: /v1/audit/verify (GET).

Name	Type	Default	Required	Description
query	Query		no	Query string parameters of the route.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

AuditResource.verifyEvidence

verifyEvidence(opts?: CallOptions)

Verify the chain and every seal. Verifies the whole tenant chain and every seal and returns tenant_id, valid, chain (hash chain result), seals (count and failures), clock (timestamp failures) and events (number checked). Needs auditor, security_officer or tenant_admin. The verification is recorded in the access log.

Route: /v1/evidence/verify (GET).

Name	Type	Default	Required	Description
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

Interface AuditRecord

Body of POST /v1/audit/events: no other field is accepted (422).

Fields:

Name	Type	Required	Description
action	app.${string}	yes	Application action in the app. namespace, for example app.invoice.validated.
resource	{ type: string; id: string; name?: string }	yes	Resource the action is about: type, id and optional name.
outcome	"success" | "failure" | "error"	no	Outcome of the action: success, failure or error.
details	Doc	no	Free attributes (at most 16384 bytes of JSON), kept under evidence.details.attributes; credentials are redacted.
classification	Classification	no	Classification of the event data.
trace_id	string	no	W3C trace id, 32 hexadecimal characters.
event_time	string	no	Client clock, ISO 8601 with a time zone.

Interface AuditRecorded

Receipt of POST /v1/audit/events.

Fields:

Name	Type	Required	Description
event_id	string	yes	Id of the recorded event.
sequence	number	yes	Ordered steps of the failover, as free objects.
hash	string	yes	Digest of the source content, for example sha256:....
prev_hash	string | null	yes	Hash of the previous event of the chain, null for the first one.
occurred_at	string	yes	Time the platform recorded the event, ISO 8601.
event_time	string | null	yes	When the action happened on the client clock (ISO 8601), at most the allowed clock skew ahead of the server. Default: the server time.
action	string	yes	Recorded action.
stream	"sdk"	yes	Audit stream of the event, always sdk.
actor	AuditEvent["actor"]	yes	Actor taken from the authentication of the call.
decision	AuditEvent["decision"]	yes	approve or reject.

Interface Span

Span built locally by TelemetryResource.startSpan and sent by endSpan.

Fields:

Name	Type	Required	Description
name	string	yes	Name of the span.
trace_id	string	yes	W3C trace id, 32 lowercase hexadecimal characters, to correlate the event with a trace.
span_id	string	yes	Random id of the span, 16 hexadecimal characters.
parent_span_id	string | null	yes	Parent span id taken from the traceparent, or null.
start_time_unix_nano	number	yes	Start time in nanoseconds since the epoch.
end_time_unix_nano	number	yes	End time in nanoseconds since the epoch, 0 while the span is open.
attributes	Doc	yes	Free attributes of the component, such as the provider of a model.
status	string	yes	Status of the span, ok until endSpan sets it.
events	Doc[]	yes	Timed events added by recordEvent.

Class TelemetryResource

Telemetry. Traces, request journal, live stream and service level objectives (SLO) of the platform.

Resource

Attributes:

Name	Type	Required	Description
body	{ availability: number; latency_seconds: number; latency_objective: number; reason?: string },	yes	Objectives sent by setSloTarget: availability, latency, latency objective and reason.
opts	CallOptions,	no	Per call options of setSloTarget.
service	string,	yes	Platform service whose objectives setSloTarget sets.

TelemetryResource.endSpan

endSpan(span: Span, status = "ok", opts?: CallOptions)

Ingest telemetry spans. Accepts up to 5000 spans and answers 202 with the number accepted, the number stored (a span already known for the same trace and span id is skipped) and the result of each exporter (ok or error). Requires a tenant principal with tenant_admin, developer or agent (403 forbidden).

Route: /v1/telemetry/spans (POST).

Name	Type	Default	Required	Description
span	Span		yes	Open span to close; an ended span throws span_ended.
status		"ok"	no	Final status of the span (default ok).
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: EaiError, the typed errors of the transport (Errors).

TelemetryResource.ingestSpans

ingestSpans(body: { spans: Doc[] } & Doc, opts?: CallOptions)

Ingest telemetry spans. Accepts up to 5000 spans and answers 202 with the number accepted, the number stored (a span already known for the same trace and span id is skipped) and the result of each exporter (ok or error). Requires a tenant principal with tenant_admin, developer or agent (403 forbidden).

Route: /v1/telemetry/spans (POST).

Name	Type	Default	Required	Description
body	{ spans: Doc[] } & Doc		yes	OTLP JSON export request (resourceSpans) or {spans: [...]} where each span has trace_id, span_id, optional parent_span_id, name, service, start_time, end_time (ISO 8601 or startTimeUnixNano / endTimeUnixNano), status, attributes, optional cost {amount, currency}, run_id and session_id.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

TelemetryResource.logs

logs(query?: { level?: "error" | "info"; service?: string; trace_id?: string; q?: string; from?: string; to?: string; limit?: number } & Query, opts?: CallOptions)

List the request journal. Request journal of the tenant from the span summaries, newest first: one line per span with its time, level (error when the span failed, else info), service, name, message (error type, or method, route and status code), duration, trace, span, run and kept attributes. Never a prompt or a model output. Requires a tenant principal with platform_admin, tenant_admin, auditor, viewer or support_engineer (403 forbidden). An unknown level or a from after to answers 400 invalid_request.

Route: /v1/telemetry/logs (GET).

Name	Type	Default	Required	Description
query	{ level?: "error" | "info"; service?: string; trace_id?: string; q?: string; from?: string; to?: string; limit?: number } & Query		no	Query string parameters of the route.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

TelemetryResource.overview

overview(query?: Query, opts?: CallOptions)

Read the telemetry overview. Dashboard of the tenant over the last days days: number of requests (root spans), errors, error rate, p50 and p95 latency in milliseconds, total cost, and per day requests, errors and cost (span costs plus the measured or estimated cost of the LLM usage events). Also says which exporters (Opik, OpenTelemetry, ClickHouse) are configured. The total cost is labelled USD. Requires a tenant principal (403 tenant_required).

Route: /v1/telemetry/overview (GET).

Name	Type	Default	Required	Description
query	Query		no	Query string parameters of the route.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

TelemetryResource.recordEvent

recordEvent(span: Span, name: string, attributes: Doc = {}): Span

Adds a timed event to an open span (no request).

Name	Type	Default	Required	Description
span	Span		yes	Open span; an ended span throws span_ended.
name	string		yes	Name of the event.
attributes	Doc	{}	no	Attributes of the event.

Returns: Span. The same span, with the event added.

Raises: EaiError.

TelemetryResource.setSloTarget

setSloTarget(service: string, body: { availability: number; latency_seconds: number; latency_objective: number; reason?: string }, opts?: CallOptions)

Set the objectives of a service. Objectives of one platform service, written in the database where they override the EAI_SLO_* defaults for every replica within 30 seconds. Platform administrator only (403 forbidden). An unknown service answers 404 slo_service_unknown. The change, with the values before and after and the reason, is audited (telemetry.slo.target.update); the answer gives the stored objectives with their version.

Route: /v1/telemetry/slo/targets/{service} (PUT).

Name	Type	Default	Required	Description
service	string		yes	Service whose objectives are set: control_plane_api, model_gateway, tool_gateway or realtime.
body	{ availability: number; latency_seconds: number; latency_objective: number; reason?: string }		yes	New availability and latency objectives of the service.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

TelemetryResource.slo

slo(query?: { window_minutes?: number; tenant_id?: string } & Query, opts?: CallOptions)

Read the SLO error budgets. For each service, over the last window_minutes minutes: requests, errors (5xx), requests over the latency target, the latency target and where it comes from (database or settings), and for availability and latency the target, bad ratio, remaining budget and burn rate. Counts are those of the replica that answers. Requires platform_admin, tenant_admin, auditor, viewer or support_engineer (403 forbidden). A platform administrator reads the whole platform or one tenant; anyone else reads only its own tenant (403 slo_scope_forbidden for another one). A window outside 1 to EAI_SLO_RETENTION_MINUTES answers 422 slo_window_invalid. Each read is audited (telemetry.slo.read).

Route: /v1/telemetry/slo (GET).

Name	Type	Default	Required	Description
query	{ window_minutes?: number; tenant_id?: string } & Query		no	Query string parameters of the route.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

TelemetryResource.startSpan

startSpan(name: string, attributes: Doc = {}, traceparent?: string): Span

Opens an explicit span (no request), child of a W3C traceparent when given.

Name	Type	Default	Required	Description
name	string		yes	Name of the span.
attributes	Doc	{}	no	Attributes of the span, copied.
traceparent	string		no	W3C traceparent of the parent; a malformed value throws validation_error.

Returns: Span. The open span, with a new trace id when no parent is given.

Raises: EaiError.

TelemetryResource.trace

trace(traceId: string, opts?: CallOptions)

Get one trace. Every span of the trace in start order (with cost when known), the span count, total duration in milliseconds, error count, the audit events that carry this trace id, and a link to the trace in Opik when Opik is configured. Requires a tenant principal (403 tenant_required). A malformed id answers 400 invalid_request; a trace without span nor audit event answers 404 not_found.

Route: /v1/telemetry/traces/{trace_id} (GET).

Name	Type	Default	Required	Description
traceId	string		yes	Trace identifier: 32 hexadecimal characters (W3C trace context), case insensitive.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

TelemetryResource.traces

traces(query?: { status?: "ok" | "error" | "unset"; service?: string; run_id?: string; from?: string; to?: string; limit?: number } & Query, opts?: CallOptions)

List the recent traces. Recent traces of the tenant, newest first: one row per root span with its name, service, start, duration, status, run, session and its span and error counts. Requires a tenant principal with platform_admin, tenant_admin, auditor, viewer or support_engineer (403 forbidden). An unknown status or a from after to answers 400 invalid_request.

Route: /v1/telemetry/traces (GET).

Name	Type	Default	Required	Description
query	{ status?: "ok" | "error" | "unset"; service?: string; run_id?: string; from?: string; to?: string; limit?: number } & Query		no	Query string parameters of the route.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).