millionways API

Behavioral intelligence for text, transcripts, and audio. Version 2 reference.

The millionways API turns human communication into structured behavioral intelligence. Developers can send text, transcripts, or audio into the API and receive machine-readable behavioral profiles that describe how a person thinks, makes decisions, regulates under pressure, collaborates, influences others, and changes over time.

The API is powered by Thorsten-4, the Large Psychology Model behind millionways. Unlike sentiment analysis, personality tagging, or general-purpose LLM prompting, Thorsten-4 does not simply summarize what someone said. It analyzes the behavioral structure beneath communication to identify deeper signals such as motivation, cognition, emotional regulation, stress response, decision style, and interpersonal dynamics.

These signals can be used to power applications across talent, leadership, investing, sales, customer intelligence, coaching, matching, public safety, and human-AI interaction.

In simple terms: millionways helps applications understand how people are likely to behave when the decision matters.

What the API does

The millionways API converts unstructured human communication into structured behavioral intelligence. You can submit inputs such as:

The API analyzes these inputs and returns structured JSON that can be stored, compared, tracked, interpreted, or used inside your own product.

Core capabilities include:

This allows developers to add a behavioral intelligence layer to existing products without building psychological models, assessment workflows, or custom interpretation systems from scratch.

About Thorsten-4

Thorsten-4 is the Large Psychology Model that powers millionways. It analyzes natural language to identify the behavioral architecture beneath communication: what drives a person, how they process information, how they respond to pressure, how they regulate emotion, how they relate to others, and where their behavior is likely to shift when stakes increase.

Thorsten-4 is not a general-purpose LLM. It is not designed to generate text, imitate a person, or produce generic coaching advice. It is designed to evaluate behavioral signal. Where LLMs generate language, Thorsten-4 analyzes the person behind the language.

Thorsten-4 is grounded in decades of psychology research and trained on expert-labeled behavioral data. Its outputs are organized into structured systems that can be used by developers, analysts, and product teams:

These systems allow applications to move beyond surface-level text analysis and model behavioral dynamics in a more precise, structured, and usable way.

Why it matters

Most software can understand what people say. millionways helps software understand the behavioral pattern behind what they say. That difference matters in high-stakes environments where outcomes depend on how people actually behave, not just what they report about themselves.

Traditional assessments depend on surveys and self-reporting. Sentiment tools detect surface emotion. General-purpose LLMs generate plausible interpretations based on broad language patterns. millionways analyzes implicit behavioral signals in real communication.

This makes it possible to model questions such as:

The result is structured behavioral intelligence that can be used inside real products, workflows, and decision systems.

What you can build

The millionways API can be used as infrastructure for products and workflows such as:

You can use millionways as a standalone behavioral analysis layer or embed it directly into your application, workflow, or enterprise system.

How it works

At a high level, the API workflow is simple:

  1. Submit communication data. Send text, transcripts, audio, or other communication artifacts to the API.
  2. Generate behavioral intelligence. Thorsten-4 analyzes the input and extracts structured behavioral signals.
  3. Create or update profiles. Use the output to create people, groups, or longitudinal behavioral records.
  4. Apply intelligence to your use case. Use the structured output for matching, scoring, interpretation, tracking, or decision support.
  5. Retrieve developer-ready JSON. The API returns structured data designed to be stored, compared, displayed, and integrated into your application.

Scientific grounding

Thorsten-4 is grounded in Personality Systems Interactions research, which models how motivation, cognition, affect, and self-regulation interact to produce behavior under pressure.

For most developers and business users, the important point is practical: Thorsten-4 does not rely on self-description. It analyzes behavioral patterns present in communication.

A person may describe themselves one way, but their language can reveal a different behavioral structure. Thorsten-4 is designed to identify that deeper structure and translate it into usable signals.

This is what enables millionways to support higher-value use cases than basic sentiment analysis, survey-based assessment, or generic LLM interpretation.

API output

The API returns structured JSON that may include:

Outputs are designed to support both human-readable applications and machine-readable workflows.

Positioning

millionways is behavioral intelligence infrastructure for applications that need to understand people more deeply. It turns unstructured human communication into structured behavioral signal, allowing developers and organizations to model how people think, decide, relate, and respond under pressure.

Use millionways when your product needs to understand not just what someone said, but how they are likely to behave.

Quickstart #

This walkthrough takes a developer from zero to a successful call against POST /v2/analyze. It uses curl only.

1. Get an API key

Request a key from your millionways contact. Keys begin with mw_live_ or mw_test_. Both behave the same way: there is no sandbox, and mw_test_ requests are processed, billed and stored like any other. Keep keys server side; do not embed them in client code.

2. Make your first request

Replace the placeholder key below with your real key, then run the command. The default mode is async, which returns a job ID immediately. For short text, sync mode usually returns the result in under one second.

curl
curl https://api.millionways.ai/v2/analyze \
  -H "Authorization: Bearer mw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "I value autonomy and prefer structured analysis over snap decisions. I take pride in delivering precise, well-reasoned work, but I find ambiguity uncomfortable.",
    "mode": "sync"
  }'

3. Read the response

In sync mode, the response body contains the full analysis. The example below is abbreviated; see the result schema reference for every field.

JSON
{
  "id": "an_xxxxxxxxxxxxxx",
  "object": "analysis",
  "created": 1774746443,
  "model": "thorsten-4",
  "motives": { "power": 26.06, "achievement": 12.03, "contact": 12.45, "dominant": "power" },
  "cognition": { "analytical": 83.12, "holistic": 16.88, "internal": 75.32, "external": 24.68 },
  "affect": { "approach": 17.5, "avoidance": 82.5, "level": 3.33 },
  "regulation": { "self_motivation": 43.38, "stress_resilience": 37.63 },
  "systems": { "dominant": "intention_memory", "personality_style": "independent" },
  "insights": { "summary": "Profile characterized by avoidance-oriented motivation, analytical thinking preference." },
  "usage": { "characters": 192, "model": "thorsten-4" }
}

4. What to do next

Authentication #

Every request needs an API key, except the public endpoints listed below. Send the key as a Bearer token in the Authorization header. The Bearer prefix is optional: a raw key in Authorization is accepted too.

HTTP
Authorization: Bearer mw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

For gateways and agent platforms that cannot set Authorization, the key is also accepted in an x-api-key, api-key, api_key or x-authorization header. Authorization wins when several are present.

Requests without a valid key return 401 authentication_error (codes missing_api_key, invalid_api_key, inactive_api_key) with a WWW-Authenticate header that points OAuth-capable clients to the protected-resource metadata. A valid key that lacks a required permission or scope returns 403 permission_error.

HTTP
WWW-Authenticate: Bearer error="invalid_token", error_description="Invalid API key", resource_metadata="https://api.millionways.ai/.well-known/oauth-protected-resource"

When no credential was sent at all, the challenge carries only resource_metadata, without an error.

Public endpoints

These need no key:

EndpointPurpose
GET /, GET /v2Welcome message with a link to this documentation.
GET /healthService health.
GET /v2/docsThis documentation, its logo, and /v2/docs/openapi.yaml.
GET /v2/skill-packageThe behavioral interpretation skill package (see MCP server).
GET /v2/behavioral-context/skillThe runtime skill for Read the room.
GET /v2/escalation-risk/skillThe guidance text for Escalation risk.
GET /.well-known/oauth-protected-resourceOAuth protected-resource metadata for MCP clients (also served at /.well-known/oauth-protected-resource/mcp).

Authentication runs before routing, so a request without a key to a path that does not exist returns 401, not 404.

Key prefixes

PrefixPurpose
mw_live_ Standard API key.
mw_test_ Behaves exactly like mw_live_: requests are processed, billed and stored the same way. There is no sandbox or test mode. The prefix only labels the key.

Permissions and scopes

Each key carries a set of permissions (new keys get analyze, chat and match) and a set of scopes (default general). Endpoints check them as follows:

RequirementEndpoints
permission: analyze POST /v2/analyze/audio, POST /v2/people/:id/analyze, /v2/interviews (all), POST /v2/behavioral-context, /v2/escalation-risk (assessment and sessions), /mcp, GET /v2/mcp/tools
permission: chat POST /v2/chat
permission: match POST /v2/match
any valid key POST /v2/analyze, GET /v2/jobs/:id, /v2/people (list, create, retrieve, update, delete), GET /v2/people/:id/trajectory

A missing permission returns 403 insufficient_permissions; a missing scope returns 403 insufficient_scope. The admin scope passes every scope check; it does not grant permissions.

MCP clients can also sign in with OAuth 2.1 instead of an API key. OAuth access tokens are for /mcp only; the REST endpoints take API keys. See MCP server.

Key handling


Making requests #

Base URL

https://api.millionways.ai

All REST endpoints documented here are prefixed with /v2. The one exception is the MCP server, which is served at the root path /mcp.

Content type

Send Content-Type: application/json with a UTF-8 encoded JSON body for all endpoints except POST /v2/analyze/audio, which expects multipart/form-data, and POST /v2/interviews/analyze, which accepts either.

Request IDs

Every response carries an x-request-id header. 5xx error bodies repeat it as error.request_id. Quote it when you contact support.

Response format

Success responses are UTF-8 JSON, except chat streams (text/event-stream). The HTTP status code follows standard conventions: 200 for synchronous success, 201 for resource creation, 202 for accepted asynchronous work, 204 for deleting a person, and 4xx/5xx for errors. The error envelope is described in Errors and retries.

Resource IDs

Every resource has a stable string ID with a prefix that indicates its type. IDs are URL-safe and case-sensitive.

PrefixResourceExample
job_ Async job (text, audio, and interview analysis) job_xxxxxxxxxxxxxx
an_ Analysis (the id inside a completed result) an_xxxxxxxxxxxxxx
pe_ Person pe_xxxxxxxxxxxxxx
ma_ Match ma_xxxxxxxxxxxxxx
ch_ Chat completion ch_xxxxxxxxxxxxxx
iu_ Interview upload iu_xxxxxxxxxxxxxx
ctx_ Behavioral context (one Read the room result) ctx_xxxxxxxxxxxxxx

Conversation, participant, turn and session IDs used by the live-conversation endpoints are chosen by you.

Timestamps

Timestamps in resource objects (analyses, people, matches, behavioral contexts, escalation assessments) are integer Unix seconds (UTC). Fields named with an _at suffix are ISO 8601 strings (for example created_at: "2024-03-15T10:22:41Z").

Two exceptions use integer Unix milliseconds: the created / completed fields of job envelopes (GET /v2/jobs/:id, GET /v2/interviews/:id; the result inside keeps seconds), and the created / updated / ts fields of an escalation session.

Idempotency

Idempotency keys are not currently supported. Treat POST calls as not-yet-idempotent; if a POST times out before returning, retrying may create a duplicate job or resource. Use the returned id to deduplicate on your side.

Async jobs and polling #

Long-running operations return a job rather than the final result. This applies to POST /v2/analyze in async mode, POST /v2/analyze/audio (always async), POST /v2/people/:id/analyze in async mode, and POST /v2/interviews/analyze (always async; polled at its own GET /v2/interviews/:id route rather than /v2/jobs/:id). Job IDs start with job_.

Job lifecycle

A job moves through these states:

StatusMeaning
queuedJob created and waiting for a worker.
processingA worker has started; the result is not yet available.
completedThe result is available in the result field.
failedThe job did not complete; check the error field.

Sync mode for short inputs

POST /v2/analyze and POST /v2/people/:id/analyze accept "mode": "sync". In sync mode the API waits for the worker to finish, up to a 60-second ceiling, and returns the full result with status 200. If the job exceeds 60 s, the API falls through to async behavior and returns 202 with a poll_url; clients should then poll GET /v2/jobs/:id. If the job fails within the 60 s, sync mode returns 500 inference_error.

Polling pattern

Poll GET /v2/jobs/:id until status is either completed or failed. Use exponential backoff to avoid unnecessary load.

AttemptWait before next call
1–31 s
4–62 s
7+5 s, capped at 30 s
✦ Most text analyses complete in well under 10 seconds. Audio jobs can take longer; use a larger maximum interval and a longer total timeout.

Recommended timeouts

Job typeRecommended client timeout
Text analysis120 s
Audio analysis15 minutes

Job retention

Job status and results are kept for one hour: a result stays retrievable for one hour after the job finishes, after which GET /v2/jobs/:id and GET /v2/interviews/:id return 404. Persist any results you need as soon as the job completes.

Pagination #

List endpoints use offset-based pagination via the limit and offset query parameters. Currently GET /v2/people is the only paginated list endpoint.

ParameterTypeDefaultDescription
limit integer 20 Maximum results to return. Minimum 1; values above 100 are capped at 100.
offset integer 0 Number of results to skip. Must be non-negative.

Response envelope

Paginated responses share a common envelope:

JSON
{
  "object": "list",
  "data": [],
  "total": 142,
  "limit": 20,
  "offset": 0
}

Iterating through all results

Increase offset by limit on each request until the returned data array is shorter than limit or offset + data.length reaches total. Avoid relying on total for in-flight inserts; if records are added during iteration, prefer filtering by created timestamp on your side to deduplicate.

Errors and retries #

All errors share a single envelope. The HTTP status code indicates the broad class of error; error.type groups it; error.code is a stable, machine-readable identifier; error.message is a human-readable description that may change without notice. Validation errors may add param, the field at fault.

JSON
{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_required_field",
    "message": "content is required",
    "param": "content"
  }
}

5xx errors never include internal details. They carry a generic message and a request_id; quote it to support.

JSON
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "8f0c2a4e-5b1d-4c7a-9e3f-2d6b1a0c9e47"
  }
}

Error types

TypeDescription
invalid_request_errorThe request body, parameters or Content-Type are malformed or invalid, or the body is too large.
authentication_errorThe API key or access token is missing, invalid, or inactive.
permission_errorThe credential is valid but lacks the required permission or scope, or the request is not allowed from its origin.
not_found_errorThe resource or route does not exist, or is not accessible to your organization.
conflict_errorThe request conflicts with the current state (for example a reused turn_id).
rate_limit_errorA per-key rate limit or daily quota was exceeded. See Rate limits.
overloaded_errorThe service or a required upstream (for example Cloud Storage) is temporarily unavailable.
api_errorAn unexpected server-side error occurred.

Errors raised before your handler runs

These use the same envelope on every endpoint:

Statustype / codeWhen
400invalid_request_error / invalid_jsonThe body is not valid JSON.
400invalid_request_error / invalid_requestThe request failed validation.
401authentication_error / missing_api_key, invalid_api_key, inactive_api_keySee Authentication. Unknown paths requested without a key also return 401.
404not_found_error / route_not_foundAuthenticated request to a route that does not exist.
413invalid_request_error / payload_too_largeThe body exceeds the size limit.
415invalid_request_error / unsupported_media_typeThe Content-Type is not accepted by the endpoint.
500api_error / internal_errorUnhandled server error. Message "Internal server error", plus request_id.

Retry guidance

StatusRetry?Recommended behavior
400 No Fix the request; retrying without changes will fail again.
401 No Check the key value and that it is active.
403 No Request a key with the required permission or scope.
404 No Verify the path and resource ID, and that the resource belongs to your organization (job results expire after one hour).
409 Depends participant_busy: retry after Retry-After. turn_already_processed: do not retry; send the new message with a new turn_id.
413 No Send a smaller body, or use the upload flow the endpoint documents.
415 No Fix the Content-Type header.
429 Yes Wait for the number of seconds in Retry-After. See Rate limits.
500 Yes Retry up to 3 times with exponential backoff. If it persists, contact support with the request_id.
503 Yes The service or an upstream dependency is unavailable. Retry with backoff.

For the full list of error.code values, see the Error codes reference.

Rate limits #

ℹ Monitoring mode. Rate limits are currently counted and logged but not enforced: no request is rejected. The behavior below describes what happens once enforcement is switched on.

Limits apply per API key, in two windows, both in UTC:

WindowCeilingResets
Minute600 requests per key (default; the same for every key)At the start of each UTC minute
DayThe key's own daily quota, set when the key is issued00:00 UTC

Keys issued without a daily quota are not rate limited at all.

What counts

When a limit is exceeded

With enforcement on, the request over a ceiling returns 429 with rate_limit_error and code rate_limit_exceeded (minute window) or daily_quota_exceeded (day window), plus these headers:

HeaderMeaning
Retry-AfterSeconds until the window resets.
X-RateLimit-LimitThe ceiling that was exceeded.
X-RateLimit-RemainingAlways 0 on a 429.
X-RateLimit-ResetWhen the window resets, in Unix seconds.
JSON — 429
{
  "error": {
    "type": "rate_limit_error",
    "code": "daily_quota_exceeded",
    "message": "Daily request quota of 500 reached for this API key. Resets at 00:00 UTC."
  }
}

Responses under the ceilings carry no rate-limit headers. There are no per-plan batch-size, audio-length or concurrency limits.

Versioning #

The API version is part of the URL path. The current major version is v2, served at https://api.millionways.ai/v2.

Compatibility within v2

Deprecation

Fields or endpoints marked as deprecated continue to function until a future major version. Deprecations are announced in the Changelog with a target removal date.

Future versions

When a new major version is introduced, it is served at a new path (for example /v3) so existing integrations are unaffected. Migration notes will be published in the Changelog before the previous major version is sunset.

SDKs #

REST is the supported integration path. Official SDKs are not published at this time. The API uses standard JSON over HTTP and works with any HTTP client.

An OpenAPI 3 specification is available at /v2/docs/openapi.yaml for generating bindings, validating requests, and importing into tools such as Postman or Insomnia.


POST /v2/analyze any valid key stable

Analyze text #

Submit text or transcript content for behavioral analysis by Thorsten-4. By default the call is asynchronous and returns a job; for short text, set "mode": "sync" to receive the full result inline.

Request body

FieldTypeDescription
contentrequired string The text to analyze. Free-form text, interview transcript, or written communication.
languageoptional string ISO 639-1 language code, recorded with the analysis. Defaults to "en". There is no translation step: text is scored as written by English-trained models, so translate non-English text to English first for reliable results.
modeoptional string Either "async" (default) or "sync". In sync mode the API waits up to 60 s for completion; on timeout it falls through to async behavior.
options.include_psioptional boolean Include PSI macrosystem and regulation fields in the result. Defaults to true.
options.include_insightsoptional boolean Include the narrative insights object. Defaults to true.
webhook_urloptional string HTTPS URL invoked once with the completed result payload when the job finishes. Delivery is best-effort with a 10-second timeout and no retries; treat it as a hint and verify completion via GET /v2/jobs/:id if delivery is critical.

Example request

curl
curl https://api.millionways.ai/v2/analyze \
  -H "Authorization: Bearer mw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "I value autonomy and prefer structured analysis over snap decisions.",
    "language": "en"
  }'

Async response 202

JSON
{
  "id": "job_xxxxxxxxxxxxxx",
  "object": "job",
  "status": "queued",
  "poll_url": "/v2/jobs/job_xxxxxxxxxxxxxx",
  "estimated_seconds": 10
}

Sync response 200

In sync mode, the response body is the full analysis object, plus a descriptions object (narrative texts for motives, affect, cognition and behavioral levels) that only the synchronous response carries. See the result schema for every field and the Retrieve job endpoint for the payload returned via polling. If the job takes longer than 60 s, the response is the 202 job above.

Common errors

StatuscodeWhen
400missing_required_fieldcontent is missing, empty, or not a string.
400invalid_field_typelanguage or webhook_url is not a string.
400invalid_enum_valuemode is not "sync" or "async".
401missing_api_key / invalid_api_keyAPI key missing or invalid.
413payload_too_largeThe JSON body exceeds 1 MiB.
500inference_errorSync mode only: the worker failed during analysis.
POST /v2/analyze/audio permission: analyze stable

Analyze audio #

Upload an audio file for transcription and behavioral analysis. The endpoint accepts multipart/form-data, stores the file, and always returns 202 with a job immediately. The worker handles transcription and per-speaker analysis. Poll GET /v2/jobs/:id for the result.

Formats and size

Form fields

FieldTypeDescription
filerequired binary The audio file, in a part named file. See Formats and size above.
languageoptional string ISO 639-1 code of the spoken language, passed to transcription. Defaults to "en"; "auto" lets transcription detect it. The transcript is scored as written (no translation step) by English-trained models.
speaker_labelsoptional string "true" to enable per-speaker diarization. Defaults to "false".
tone_analysisoptional string "true" to additionally run voice tone analysis on the recording. Defaults to "false". The result is returned under tone_analysis in the completed job. Failsafe — if tone analysis is unavailable or errors, the transcript and behavioral profile are still returned.
dissonanceoptional string "true" to additionally compute Dissonance Analysis — per-dimension text-vs-tone divergence for every Thorsten signal, returned under dissonance in the completed job. Requires tone_analysis=true (otherwise 400 dissonance_requires_tone). Failsafe — never blocks the behavioral result.
optionsoptional string (JSON) JSON-encoded options object. Supports include_psi and include_insights booleans, both defaulting to true. A value that is not valid JSON is ignored (defaults apply).
webhook_urloptional string HTTPS URL invoked once with the completed payload. Best-effort with a 10-second timeout and no retries.

Boolean form fields accept "true" or "1"; any other value counts as false.

Example request

curl
curl https://api.millionways.ai/v2/analyze/audio \
  -H "Authorization: Bearer mw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@/path/to/interview.mp3" \
  -F "language=en" \
  -F "speaker_labels=true" \
  -F "tone_analysis=true" \
  -F "dissonance=true"

Response 202

JSON
{
  "id": "job_xxxxxxxxxxxxxx",
  "object": "job",
  "status": "queued",
  "poll_url": "/v2/jobs/job_xxxxxxxxxxxxxx",
  "estimated_seconds": 80
}

estimated_seconds is a fixed estimate: 30, plus 20 with speaker_labels, plus 30 with tone_analysis. It does not account for recording length; long recordings take longer.

Completed result

When the job completes, GET /v2/jobs/:id returns the standard analysis result with audio-specific additions: a transcript object, usage.audio_seconds, and, when speaker_labels was enabled and speakers were detected, a per-speaker analyses array. In that case the top-level profile is the first speaker's, and each speaker entry also carries its own tone and dissonance when those options are on. Transcription runs on millionways' managed speech-to-text pipeline with automatic fallback for reliability.

JSON — result excerpt
{
  "transcript": {
    "text": "Full transcript...",
    "duration_seconds": 342,
    "speakers": [
      { "id": "speaker_0", "segments": [ { "start": 0.0, "end": 4.2, "text": "Welcome everyone..." } ] }
    ]
  },
  "analyses": [
    { "speaker": "speaker_0", "motives": {}, "cognition": {}, "affect": {} }
  ]
}

tone_analysis

When tone_analysis=true, the result also carries a tone_analysis object. Voice tone is the acoustic/paralinguistic state of the speaker — complementary to the language-derived behavioral profile. The voice tone engine's own speech-to-text is disabled; the transcript above comes from the transcription pipeline. The object surfaces every emotion dimension: per-channel reports (emotion profile, aggregate tags, edp flags, testReport), a time-stamped per-segment segments array, and technical metadata.

JSON — tone_analysis
{
  "tone_analysis": {
    "success": true,
    "reports": {
      "channel-0": {
        "profile": { "stress": { "averageLevel": 8.44, "highPercentage": 4.41 }, "uncertainty": {}, "joy": {} },
        "tags": ["#HIGH-UNCERTAINTY", "#LOGICAL-CALL"],
        "edp": { "EDP-Stressful": 60, "EDP-Concentrated": 61 },
        "testReport": { "extremeStressSegments": 4, "extremeEmotionSegments": 0 }
      },
      "channel-1": { "testReport": { "error": "File contains 0 segments." } }
    },
    "segments": [
      { "index": 1, "channel": 0, "startPosSec": 0.098, "endPosSec": 1.794, "validSegment": true,
        "stress": 18, "uncertainty": 20, "hesitation": 16, "joy": 0, "valance": -10, "feelGPT": "[stressed:6;engaged:4]" }
    ],
    "technical": { "audioDuration": 128.27, "audioChannelsCount": 2, "segmentsCount": 74 }
  }
}
ℹ Failsafe. Tone analysis never blocks the behavioral result. If tone analysis is not configured, errors, or the clip is too short (it needs roughly 20–30 s of clear speech), tone_analysis instead carries { "error": "..." } and the transcript and profile are still returned. A per-channel testReport.error or any -1000 metric means there is no usable data for that channel.

dissonance

When dissonance=true (which requires tone_analysis=true), the result also carries a dissonance object: deterministic text-vs-tone scoring for every Thorsten dimension — all 34 native signals (across Motives, Cognition, Affect, Stress State, Regulation, Systems, Styles) plus the 15 submotives. Each dimension compares its raw Thorsten score (0–100) with a mapped voice signal (0–100): dissonance_score = |thorsten_score − comparable_emlo_score|, where comparable_emlo_score is the voice score for direct polarity or 100 − emlo_score for inverse. Results are grouped by system; each dimension carries its band, a direction (text_higher / tone_higher / aligned), a type label, and an end-user interpretation. There is no single overall score — the strongest dimension is primary_dissonance.

JSON — dissonance
{
  "dissonance": {
    "primary_dissonance": {
      "key": "power", "system": "Motives", "signal": "Power",
      "dissonance_type": "Power-Aggression Split",
      "dissonance_score": 93.3, "dissonance_level": "very_high", "direction": "text_higher"
    },
    "groups": {
      "motives": [
        { "key": "power", "system": "Motives", "group": "motives", "signal": "Power",
          "thorsten_field": "motives.power", "thorsten_score": 97.06,
          "emlo_signal": "Aggression", "emlo_score": 3.76,
          "polarity": "direct", "comparable_emlo_score": 3.76,
          "dissonance_score": 93.3, "dissonance_level": "very_high", "direction": "text_higher",
          "dissonance_type": "Power-Aggression Split",
          "interpretation": "This compares influence in the words with force in the voice..." }
      ],
      "cognition": [], "affect": [], "stress_state": [],
      "regulation": [], "systems": [], "styles": [], "submotives": []
    },
    "signal_confidence": 1.0,
    "coverage": { "computed": ["power", "..."], "skipped_no_emlo_column": [], "skipped_missing_text": [] },
    "disclaimer": "Dissonance Analysis does not determine whether a person is lying or being deceptive..."
  }
}
ℹ Not deception detection. Dissonance flags a gap between channels that may reflect stress, masking, cognitive load, topic sensitivity, or normal individual variation — a follow-up signal, not a verdict. Raw voice emotion markers (0–30) are normalized to 0–100; the Confidence voice signal is derived as 100 − mean(uncertainty, hesitation).

Common errors

StatuscodeWhen
400missing_required_fieldNo file field was sent or it was empty.
400file_too_largeFile exceeds the API's 100 MB limit (in practice the 32 MiB front-end limit applies first).
413—Request body over 32 MiB, rejected by the hosting front end (may not be a JSON body).
400unsupported_formatContent type or extension is not in the accepted set.
400upload_errorThe request is not multipart/form-data, or the multipart stream could not be read.
400dissonance_requires_tonedissonance=true was sent without tone_analysis=true.
403insufficient_permissionsThe key lacks the analyze permission.
503storage_not_configuredAudio storage is not configured for this environment. Contact support.
503(storage code)Cloud Storage rejected the upload. Retry with backoff.
500storage_errorThe file could not be persisted to storage.
GET /v2/jobs/:id any valid key stable

Retrieve a job #

Poll the status of an asynchronous job from POST /v2/analyze, POST /v2/analyze/audio or POST /v2/people/:id/analyze. When status is completed the full analysis result is available in the result field. Jobs that belong to a different organization, or whose result has expired (one hour after completion), return 404. The envelope's created and completed are Unix milliseconds.

Path parameters

ParameterTypeDescription
idrequired string The job ID returned by an analyze call (for example job_xxxxxxxxxxxxxx).

Response — queued / processing 200

JSON
{
  "id": "job_xxxxxxxxxxxxxx",
  "object": "job",
  "status": "processing",
  "created": 1774746000000
}

Response — completed 200

All scores below are illustrative. The full field reference is in Result schema.

JSON
{
  "id": "job_xxxxxxxxxxxxxx",
  "status": "completed",
  "created": 1774746000000,
  "completed": 1774746443000,
  "result": {
    "id": "an_xxxxxxxxxxxxxx",
    "object": "analysis",
    "created": 1774746443,
    "model": "thorsten-4",
    "motives": {
      "power": 26.06,
      "achievement": 12.03,
      "contact": 12.45,
      "dominant": "power",
      "prediction": "0",
      "confidence_scores": { "0": 0.494606, "M-3": 0.085659, "M-4": 0.089474 }
    },
    "cognition": {
      "detail": 2.6,
      "realization": 97.4,
      "analytical": 83.12,
      "holistic": 16.88,
      "internal": 75.32,
      "external": 24.68,
      "goal": 89.61,
      "path": 10.39
    },
    "affect": {
      "approach": 17.5,
      "avoidance": 82.5,
      "positive": 34.31,
      "negative": 66.94,
      "level": 3.33,
      "level_distribution": { "level1": 8.59, "level2": 13.21, "level3": 31.46, "level4": 30.13, "level5": 16.61 }
    },
    "regulation": {
      "self_motivation": 43.38,
      "self_relaxation": 24.74,
      "action_orientation_failure": 36.09,
      "action_orientation_decision": 48.14,
      "volitional_efficiency": 38.9,
      "stress_resilience": 37.63
    },
    "systems": {
      "extension_memory": 31.49,
      "object_recognition": 36.3,
      "intention_memory": 80.16,
      "intuitive_behavior": 34.52,
      "dominant": "intention_memory",
      "personality_style": "independent",
      "style_scores": { "agreeable": 34.52, "self_determined": 31.49, "conscientious": 36.3, "independent": 80.16 }
    },
    "insights": {
      "summary": "Profile characterized by avoidance-oriented motivation, analytical thinking preference.",
      "strengths": ["Systematic, data-driven decision making", "Structured planning and follow-through"],
      "development_areas": ["Building approach motivation and forward momentum", "Self-regulation and downregulation capacity"]
    },
    "usage": { "characters": 45430, "model": "thorsten-4" }
  }
}

Response — failed 200

JSON
{
  "id": "job_xxxxxxxxxxxxxx",
  "status": "failed",
  "created": 1774746000000,
  "completed": 1774746012000,
  "error": "Inference worker timed out"
}
ℹ The endpoint returns 200 even when status is failed. Inspect the status field, not the HTTP code, to detect job failures.

Common errors

StatuscodeWhen
404job_not_foundThe job does not exist, has expired, or belongs to a different organization.
POST /v2/match permission: match stable

Match #

Compute compatibility between two profiles across motives, cognition, affect, regulation, and systems dimensions. Returns an overall score, per-dimension scores, and narrative insights.

Input modes

The endpoint accepts profiles in either of two ways. Provide exactly one mode per request.

Request body

FieldTypeDescription
analysis_a string ID of the first stored analysis. Mutually exclusive with profile_a.
analysis_b string ID of the second stored analysis. Mutually exclusive with profile_b.
profile_a object Inline profile object containing at least motives. Mutually exclusive with analysis_a.
profile_b object Inline profile object containing at least motives. Mutually exclusive with analysis_b.
contextoptional string A short context tag (for example "team", "leadership", "sales"). Stored with the match record; it does not currently change the scores or insights.

Example request — by analysis ID

curl
curl https://api.millionways.ai/v2/match \
  -H "Authorization: Bearer mw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "analysis_a": "an_xxxxxxxxxxxxxx",
    "analysis_b": "an_yyyyyyyyyyyyyy",
    "context": "team"
  }'

Response 200

JSON
{
  "id": "ma_xxxxxxxxxxxxxx",
  "object": "match",
  "score": 74,
  "compatibility": {
    "overall": 74,
    "motives": 81,
    "cognition": 68,
    "affect": 77,
    "regulation": 72,
    "systems": 70
  },
  "insights": {
    "strengths": [
      "Both individuals share high achievement motivation",
      "Complementary cognition styles enhance problem-solving"
    ],
    "challenges": [
      "Differing avoidance profiles may surface under pressure"
    ],
    "recommendations": [
      "Establish clear role ownership to reduce friction",
      "Leverage individual analytical strengths for strategy sessions"
    ]
  },
  "created": 1774746443
}

score equals compatibility.overall. All compatibility values are integers from 0 to 100.

Common errors

StatuscodeWhen
400missing_required_fieldNeither (profile_a + profile_b) nor (analysis_a + analysis_b) was provided, or only one analysis ID was.
400conflicting_fieldsBoth inline profiles and analysis IDs were provided in the same request.
400invalid_field_valueAn inline profile is not an object or has no motives object.
400invalid_field_typecontext is not a string.
403insufficient_permissionsAPI key lacks the match permission.
404analysis_not_foundA referenced analysis does not exist in your organization.
500db_errorThe match could not be stored.
POST /v2/chat permission: chat stable

Chat #

Conversational endpoint grounded in behavioral intelligence. Accepts a list of messages, optionally with the profile of the person being discussed, and returns an assistant response written by a large language model, optionally as a Server-Sent Events stream.

Request body

FieldTypeDescription
messagesrequired array of object Conversation history. Each item is { "role": "user" | "assistant", "content": string } with non-empty content. The array must contain at least one user message; the latest user message is the request.
analysis_idoptional string ID of a stored analysis in your organization (an_…) to ground the answer in that person's profile.
profileoptional object An inline profile (for example a completed analysis result) to ground the answer in. Ignored when analysis_id is set.
contextoptional string Domain preset: hr, leadership, coaching, hiring, sales, support, finance, health, empathy, legal, consumer, marketing. Other values (including general) let the router infer the scenario from the message.
system_promptoptional string Additional instructions appended to the built-in system prompt.
streamoptional boolean If true, the response is delivered as an SSE stream. Defaults to false.
modeloptional string Backing language model. "auto" (default) uses the platform default. A provider name (openai, anthropic, google, or the aliases chatgpt, gpt, claude, gemini) selects that provider's latest model; an explicit provider/model ID is passed through.
max_tokensoptional integer Maximum tokens in the assistant response. Defaults to 4096 (1000 for a clarifying-question turn).
conversation_stateoptional object State you carry across turns of a multi-turn thread (the API does not return it). Optional; the message history alone is enough for most integrations.

The endpoint also accepts structured context fields used by the millionways platform (participants, environment, scenario_prompt, org_context, is_system_follow_up, original_scenario_prompt, levels, psi). They are optional and not needed for a standard integration.

Example request

curl
curl https://api.millionways.ai/v2/chat \
  -H "Authorization: Bearer mw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Summarize the behavioral pattern in this profile and where it is likely to degrade under pressure." }
    ],
    "analysis_id": "an_xxxxxxxxxxxxxx"
  }'

Non-streaming response 200

JSON
{
  "id": "ch_xxxxxxxxxxxxxx",
  "object": "chat.completion",
  "model_used": "openai/gpt-6.1-sol",
  "content": "The profile is analytical, internal, and goal-oriented, with low approach affect and below-average stress resilience. Under sustained pressure, expect slower decision initiation and reduced volitional efficiency before any drop in analytical quality.",
  "usage": { "prompt_tokens": 3120, "completion_tokens": 89, "total_tokens": 3209 },
  "branch": "scenario",
  "environment": "talent_leadership",
  "scenario_type": null,
  "response_pattern": null,
  "transcript_evidence_available": false,
  "follow_ups": [
    { "label": "Summarize this", "bucket": "format" }
  ]
}

model_used names the language model that wrote the answer. branch, environment, scenario_type and response_pattern describe how the request was routed; follow_ups are suggested next prompts. When the router cannot tell what is being asked, the reply is a single clarifying question with branch: "clarify".

Streaming response (SSE)

When "stream": true, the response is text/event-stream and the chat ID is also in the X-Chat-Id header. Each event is a data: line carrying JSON: first one chat.metadata event, then chat.chunk events, then one chat.done event, and finally the literal line data: [DONE]. An error during the stream is sent as data: {"error": {"type": "api_error", "message": …}} followed by data: [DONE].

SSE
data: {"id":"ch_xxxxxxxxxxxxxx","object":"chat.metadata","branch":"scenario","environment":"talent_leadership","scenario_type":null,"response_pattern":null,"transcript_evidence_available":false}
data: {"id":"ch_xxxxxxxxxxxxxx","object":"chat.chunk","content":"The"}
data: {"id":"ch_xxxxxxxxxxxxxx","object":"chat.chunk","content":" profile"}
data: {"id":"ch_xxxxxxxxxxxxxx","object":"chat.done","model_used":"openai/gpt-6.1-sol","usage":{"prompt_tokens":3120,"completion_tokens":89,"total_tokens":3209},"follow_ups":[{"label":"Summarize this","bucket":"format"}]}
data: [DONE]

Common errors

StatuscodeWhen
400missing_required_fieldmessages is missing, not an array, or empty.
400invalid_field_valueAn item in messages has empty or non-string content, or the array contains no user message.
400invalid_enum_valueAn item in messages has a role other than user or assistant.
400unknown_modelmodel is not a recognized model or provider.
400provider_not_configuredThe selected provider is not available.
403insufficient_permissionsAPI key lacks the chat permission.
404analysis_not_foundanalysis_id does not exist in your organization.
500llm_errorThe language model provider returned an error.
GET /v2/people any valid key stable

List people #

Return a paginated list of people in your organization with optional tag filtering and name search.

Query parameters

ParameterTypeDescription
limitoptionalintegerResults per page. Default 20; values above 100 are capped at 100.
offsetoptionalintegerPagination offset. Default 0.
tagoptionalstringFilter by an exact tag.
searchoptionalstringCase-insensitive name match.

Response 200

JSON
{
  "object": "list",
  "data": [
    {
      "id": "pe_xxxxxxxxxxxxxx",
      "object": "person",
      "name": "Jane Doe",
      "role": "Engineering Lead",
      "organization": "Acme Corp",
      "tags": ["leadership", "engineering"],
      "metadata": {},
      "analysis_count": 3,
      "latest_analysis": null,
      "created": 1710497761,
      "updated": 1710497761
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

In list results latest_analysis is always null; retrieve a person to get it.

Common errors

StatuscodeWhen
400invalid_field_valuelimit is not a positive integer, or offset is negative or not an integer.
POST /v2/people any valid key stable

Create a person #

Create a person record. People are the unit by which analyses are linked over time. All body fields are optional; an empty person can be created and populated later.

Request body

FieldTypeDescription
nameoptionalstringFull name.
roleoptionalstringJob title or role.
organizationoptionalstringThe person's organization name.
tagsoptionalarray of stringFree-form labels used for filtering in GET /v2/people.
metadataoptionalobjectArbitrary key-value data attached to this record.

Example request

curl
curl https://api.millionways.ai/v2/people \
  -H "Authorization: Bearer mw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "role": "Engineering Lead",
    "organization": "Acme Corp",
    "tags": ["leadership", "engineering"]
  }'

Response 201

JSON
{
  "id": "pe_xxxxxxxxxxxxxx",
  "object": "person",
  "name": "Jane Doe",
  "role": "Engineering Lead",
  "organization": "Acme Corp",
  "tags": ["leadership", "engineering"],
  "metadata": {},
  "analysis_count": 0,
  "latest_analysis": null,
  "created": 1710497761,
  "updated": 1710497761
}

Common errors

StatuscodeWhen
400invalid_field_typename is not a string, tags is not an array, or metadata is not an object.
GET /v2/people/:id any valid key stable

Retrieve a person #

Return a person record together with the count of analyses attached to them and the latest analysis summary if any.

Path parameters

ParameterTypeDescription
idrequiredstringPerson ID (for example pe_xxxxxxxxxxxxxx).

Response 200

Same shape as Create a person, with analysis_count reflecting all analyses currently attached.

Common errors

StatuscodeWhen
404person_not_foundNo person with that ID exists in the calling organization.
PATCH /v2/people/:id any valid key stable

Update a person #

Partial update. Only the fields supplied in the request body are changed; other fields are left untouched. To clear a field, send null for it (where the schema allows null).

Request body

FieldTypeDescription
nameoptionalstring or nullReplace the person's name. Pass null to clear.
roleoptionalstring or nullReplace the person's role.
organizationoptionalstring or nullReplace the organization name.
tagsoptionalarray of string or nullReplace the tag list (full overwrite, not merge).
metadataoptionalobjectReplace the metadata object.

Response 200

Returns the updated person object. In this response analysis_count is 0 and latest_analysis is null; retrieve the person for current values.

Common errors

StatuscodeWhen
400invalid_field_typename is not a string or null, tags is not an array or null, or metadata is not an object.
404person_not_foundNo person with that ID exists in the calling organization.
DELETE /v2/people/:id any valid key stable

Delete a person #

Permanently delete a person and all analyses, matches, and trajectory data attached to them. Returns 204 No Content on success. The deletion is recorded in the audit log.

⚠ Deletion is hard and cannot be undone. Cascades to all analyses and match records linked to this person.

Response

204 No Content with an empty body.

Common errors

StatuscodeWhen
404person_not_foundNo person with that ID exists in the calling organization.
POST /v2/people/:id/analyze permission: analyze stable

Analyze for a person #

Run an analysis and attach the result to the specified person. This is equivalent to POST /v2/analyze with an additional persistence step that links the resulting analysis to :id for use by the trajectory and people endpoints.

Request body

Same fields as POST /v2/analyze: content (required), language, mode, options, webhook_url.

Example request

curl
curl https://api.millionways.ai/v2/people/pe_xxxxxxxxxxxxxx/analyze \
  -H "Authorization: Bearer mw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Q3 retrospective notes...",
    "mode": "sync"
  }'

Response

In sync mode, returns the analysis object directly with 200 (without the descriptions object that POST /v2/analyze adds). In async mode (default), or when sync mode exceeds 60 s, returns 202 with a job ID and poll URL, identical in shape to POST /v2/analyze.

Common errors

StatuscodeWhen
403insufficient_permissionsAPI key lacks the analyze permission.
404person_not_foundNo person with that ID exists in the calling organization.
400missing_required_fieldcontent is missing or not a string.
400invalid_enum_valuemode is not "sync" or "async".
500inference_errorSync mode only: the worker failed during analysis.
GET /v2/people/:id/trajectory any valid key stable

Person trajectory #

Return the longitudinal sequence of analyses attached to a person, sorted by creation time ascending. Each data point contains the affect, regulation, and systems sections of the corresponding analysis — the fields most useful for plotting change over time.

Path parameters

ParameterTypeDescription
idrequiredstringPerson ID.

Response 200

JSON
{
  "person_id": "pe_xxxxxxxxxxxxxx",
  "data_points": [
    {
      "analysis_id": "an_xxxxxxxxxxxxxx",
      "created": 1710497761,
      "affect": { "approach": 17.5, "avoidance": 82.5, "level": 3.33 },
      "regulation": { "self_motivation": 43.38, "stress_resilience": 37.63 },
      "systems": { "dominant": "intention_memory", "personality_style": "independent" }
    }
  ]
}

Common errors

StatuscodeWhen
404person_not_foundNo person with that ID exists in the calling organization.

POST /v2/interviews/uploads permission: analyze stable

Create interview upload #

Mint a short-lived upload URL for an interview video. Your client then PUTs the file directly to millionways-managed cloud storage — the video never transits the API server, so uploads are not subject to the request-size limits of the API edge. Videos up to 2 GB are accepted for analysis. This is the recommended way to submit interview recordings of any real length.

Request body

All fields are optional; they help the server pick the right storage content type. Without them the video is treated as mp4.

FieldTypeDescription
filenameoptional string Original filename, e.g. "interview.mov". Used to infer the video format from the extension.
content_typeoptional string Video MIME type, e.g. "video/quicktime". Takes precedence over the filename extension.

Example request

curl
curl https://api.millionways.ai/v2/interviews/uploads \
  -H "Authorization: Bearer mw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "filename": "interview.mp4", "content_type": "video/mp4" }'

Response 200

JSON
{
  "object": "interview_upload",
  "upload_ref": "iu_xxxxxxxxxxxxxx",
  "gcs_uri": "gs://bucket/org_xxxx/interviews/uploads/iu_xxxxxxxxxxxxxx.mp4",
  "upload_url": "https://storage.googleapis.com/…long-signed-url…",
  "method": "PUT",
  "headers": {},
  "expires_in": 604800,
  "next": "PUT the video to upload_url (single request, set Content-Length), then POST /v2/interviews/analyze { \"upload_ref\": \"iu_xxxxxxxxxxxxxx\", \"interview_id\": \"…\" }"
}

The upload URL stays valid for 7 days (expires_in, in seconds), but upload_ref is only valid for 24 hours after it is created. Pass it to Analyze interview once the upload finishes; after 24 hours, reference the uploaded file by its gcs_uri instead.

Uploading the video

Send the whole file in a single PUT to upload_url with Content-Length set (no extra headers, no Content-Type, no Content-Range):

curl
curl -X PUT "<upload_url>" --upload-file /path/to/interview.mp4

Common errors

StatuscodeWhen
503storage_not_configuredUpload storage is not configured for this environment. Contact support.
503upload_session_errorAn upload session could not be created. Retry with backoff.
POST /v2/interviews/analyze permission: analyze stable

Analyze interview #

Run an Interview Integrity Analysis on a recorded interview video. The pipeline extracts the audio, transcribes and diarizes it, separates the candidate from the interviewer, and analyzes every candidate answer with Thorsten-4 behavioral analysis, voice tone analysis, and text-vs-tone dissonance scoring. The result is four calibrated integrity composites — ai_assisted, speaker_continuity, authenticity, and high_concern — plus full per-answer detail.

The endpoint is always asynchronous: it returns 202 with a job immediately. Poll GET /v2/interviews/:id for the result. A one-hour interview typically completes in a few minutes.

⚠ Review signal, not a verdict. Integrity composites flag interviews for human review. They do not prove deception, fraud, or candidate misconduct, and must not be used as the sole basis for employment decisions. Every result carries a safe_use_notice restating this.

Input modes

There are two ways to provide the video:

Request body — reference mode (JSON)

FieldTypeDescription
upload_refrequired* string Upload reference from POST /v2/interviews/uploads. *Provide either upload_ref or gcs_uri.
gcs_urioptional string Alternative to upload_ref: the gs:// URI of an uploaded object. Must be under your organization's upload prefix, otherwise 403 gcs_uri_forbidden.
interview_idoptional string Your identifier for the interview (e.g. from your ATS or interview platform). Echoed back in the result.
candidate_refoptional string Anonymized candidate reference, stored with the job.
customer_id, interview_stage, source_systemoptional string Free-form metadata stored with the job for your own bookkeeping.
languageoptional string ISO 639-1 hint. Transcription auto-detects the spoken language regardless; non-English candidate answers are automatically translated to English before behavioral analysis (the result records source_language and translated_to_english).
webhook_urloptional string HTTPS URL invoked once with the completed payload. Best-effort with a 10-second timeout and no retries.

Request body — multipart mode

Send the video as a file field. Accepted formats: mp4, mov, webm, mkv, m4v, avi. The file is streamed straight to storage and never buffered on the API server. All metadata fields above can be sent as additional form fields.

Example request

curl
curl https://api.millionways.ai/v2/interviews/analyze \
  -H "Authorization: Bearer mw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_ref": "iu_xxxxxxxxxxxxxx",
    "interview_id": "int_84213",
    "candidate_ref": "cand_5521"
  }'

Response 202

JSON
{
  "id": "job_xxxxxxxxxxxxxx",
  "object": "job",
  "status": "received",
  "poll_url": "/v2/interviews/job_xxxxxxxxxxxxxx",
  "estimated_seconds": 460
}

Common errors

StatuscodeWhen
400missing_required_fieldNeither upload_ref nor gcs_uri was provided (JSON mode), or no file field was sent (multipart mode).
404upload_not_foundThe upload_ref does not exist, is older than 24 hours, or belongs to another organization. Use the upload's gcs_uri, or request a fresh URL.
400upload_not_foundNo object exists at the referenced storage location — the PUT to the upload URL never completed.
403gcs_uri_forbiddengcs_uri points outside your organization's upload prefix.
400file_too_largeThe video exceeds the 2 GB limit (reference mode) or the multipart cap (use reference mode instead).
400unsupported_formatThe file is not one of the accepted video formats.
503storage_not_configuredUpload storage is not configured for this environment. Contact support.
GET /v2/interviews/:id permission: analyze stable

Retrieve interview analysis #

Poll the status of an interview analysis and fetch the result once complete. Use the job id returned by Analyze interview. status moves through queued, processing, then complete or failed. The result stays available for one hour after the job finishes; store it. The envelope's created and completed are Unix milliseconds.

Path parameters

ParameterTypeDescription
idrequired string The job ID from the 202 response.

Response — queued / processing 200

JSON
{
  "id": "job_xxxxxxxxxxxxxx",
  "object": "job",
  "status": "queued",
  "created": 1774746000000
}

The integrity composites

The heart of the result is result.interview.composites — four calibrated review signals, each scored 0–100:

CompositeWhat it flags
ai_assistedSigns the answers were generated and read aloud — over-structured, low-spontaneity language combined with vocal strain consistent with reading.
speaker_continuityVocal-change detector — a possible mid-interview speaker swap. Low confidence; treat as a prompt to check the recording.
authenticityRehearsed or coached response patterns — inconsistent detail structure and high text-vs-tone dissonance.
high_concernCombined behavioral-pressure signal — sustained dissonance, shifting vocal distress, and affect extremes.

Each composite carries a score (0–100), a risk_level band (very_low ≤ 20, low ≤ 40, moderate ≤ 60, high ≤ 80, very_high above), plain-language drivers explaining what pushed the score up (present when the score reaches 40), and a review_recommendation label ("no_review_indicated" when nothing warrants review). There is intentionally no single overall score — the interview-level review_recommendation reflects the strongest composite.

Response — completed 200

All scores below are illustrative and abbreviated. segments carries one entry per scored candidate answer (up to 40) with the same Thorsten profile, tone averages, and dissonance detail documented under Analyze audio.

JSON
{
  "id": "job_xxxxxxxxxxxxxx",
  "object": "interview_analysis",
  "status": "complete",
  "created": 1774746000000,
  "completed": 1774746238000,
  "result": {
    "id": "an_xxxxxxxxxxxxxx",
    "object": "interview_analysis",
    "created": 1774746238,
    "interview_id": "int_84213",
    "interview": {
      "composites": {
        "ai_assisted":        { "score": 12, "risk_level": "very_low", "drivers": [], "review_recommendation": "no_review_indicated" },
        "speaker_continuity": { "score": 4,  "risk_level": "very_low", "drivers": [], "review_recommendation": "no_review_indicated" },
        "authenticity":       { "score": 55, "risk_level": "moderate",
                                "drivers": ["Rehearsed / inconsistent response pattern", "High text–tone dissonance"],
                                "review_recommendation": "Elevated authenticity / coached-response risk" },
        "high_concern":       { "score": 31, "risk_level": "low", "drivers": [], "review_recommendation": "no_review_indicated" }
      },
      "num_answers": 24,
      "review_recommendation": "Elevated authenticity / coached-response risk",
      "safe_use_notice": "This score is an interview integrity review signal. It does not prove deception, fraud, or candidate misconduct and should not be used as the sole basis for employment decisions."
    },
    "speaker_separation": {
      "candidate_speaker": "B",
      "interviewer_speaker": "A",
      "method": "interviewer_script_v1",
      "candidate_track_contamination": 0.08,
      "speakers": [
        { "id": "A", "talk_time_s": 412.6, "is_first": true, "first_words": "Thanks for joining — to start, walk me through…",
          "interviewer_likelihood": 0.91, "question_ratio": 0.62, "script_hits": 3, "answer_marker_hits": 0, "role": "interviewer" },
        { "id": "B", "talk_time_s": 1841.2, "is_first": false, "first_words": "Sure — in my last role I was responsible for…",
          "interviewer_likelihood": 0.08, "question_ratio": 0.04, "script_hits": 0, "answer_marker_hits": 5, "role": "candidate" }
      ],
      "warnings": []
    },
    "source_language": "en",
    "translated_to_english": false,
    "segments": [
      {
        "index": 0, "start": 41.9, "end": 118.4,
        "answer_excerpt": "Sure — in my last role I was responsible for…",
        "thorsten": { "motives": {}, "cognition": {}, "affect": {}, "regulation": {}, "systems": {} },
        "tone_averages": { "stress": 18.2, "uncertainty": 21.5, "hesitation": 14.8 },
        "dissonance": {
          "primary_dissonance": { "key": "power", "system": "Motives", "signal": "Power",
            "dissonance_type": "Power-Aggression Split", "dissonance_score": 61.3,
            "dissonance_level": "high", "direction": "text_higher" },
          "groups": { "motives": [], "cognition": [], "affect": [], "stress_state": [],
                      "regulation": [], "systems": [], "styles": [], "submotives": [] }
        }
      }
    ],
    "transcript": { "text": "Full interview transcript…", "duration_seconds": 2254, "candidate_speaker": "B", "source_language": "en" },
    "warnings": [],
    "safe_use_notice": "This score is an interview integrity review signal. It does not prove deception, fraud, or candidate misconduct and should not be used as the sole basis for employment decisions."
  }
}

Result fields

FieldDescription
interviewThe four integrity composites, num_answers (how many candidate answers were scored), the interview-level review_recommendation, and the safe_use_notice.
speaker_separationHow the candidate was identified: candidate/interviewer speaker labels, the separation method, a candidate_track_contamination estimate (0–1; how much interviewer-like speech leaked into the candidate track), and per-speaker diagnostics (talk_time_s, interviewer_likelihood, question_ratio, role, …).
segmentsOne entry per scored candidate answer (capped at 40): timing, a 240-character answer_excerpt, the answer's full Thorsten profile, its pooled tone_averages (null when the tone signal is unavailable), and its per-dimension dissonance comparison trimmed to score fields.
source_language / translated_to_englishThe detected spoken language, and whether answers were translated to English before behavioral analysis.
transcriptThe full interview transcript with duration and the candidate's speaker label.
warningsNon-fatal notices, e.g. "translated_to_english_from_de", "tone_analysis_unavailable_dissonance_limited", or "insufficient_candidate_speech".
ℹ Insufficient candidate speech. If no scorable candidate answers are found, the result still completes: it carries status_detail: "insufficient_candidate_speech", zero-scored composites with review_recommendation: "no_candidate_speech", and the transcript for manual inspection.

Response — failed 200

JSON
{
  "id": "job_xxxxxxxxxxxxxx",
  "status": "failed",
  "created": 1774746000000,
  "completed": 1774746041000,
  "error": "Audio could not be extracted from the video"
}

Common errors

StatuscodeWhen
404job_not_foundThe interview does not exist or belongs to a different organization.

POST /v2/behavioral-context permission: analyze beta

Read the room #

Behavioral context for live conversations. Call it once per participant message, before your agent replies. Each call reads one participant from their own words and returns: conversational events in this message (pulling back, pausing, re-engaging, accepting a step you offered, asking for a different step, asking for an owner or a person); how the participant seems and whether that read applies to this message; how they like to be communicated with; what changed versus their own earlier messages; and one resolved recommendation for the next reply. The same engine backs the MCP tool read_room.

The response is synchronous. State is kept per organization, conversation and participant for 24 hours after the last turn. The guidance is produced by deterministic rules; your agent writes the reply.

⚠ Shapes how your agent replies, never what is true. The result never overrides your agent's task, facts or permissions, and never establishes that an action happened (a case opened, a callback booked). Never tell the participant about the read, scores or psychology, and never use it to deny service, judge, diagnose or take adverse action.

Request body

FieldTypeDescription
conversation_idrequired string Stable ID for the whole conversation. 1–128 characters: letters, digits, . _ : -.
participant_idrequired string Stable ID for the person whose words these are (for example "customer"). One ID per person; in a group, call once per participant. Same character rules.
turn_idrequired string Unique ID for this message. Reuse it only to retry the same message. Same character rules.
messagerequired string The participant's own words for this turn, verbatim. 1–20,000 characters. Never your words, a summary, or other people's messages.
recipe_idoptional string "general-v2" (default; any conversation), "support-v2" (customer support: adds policy with risk, recommended action, engagement, resolution and routing), or "general-v1" / "support-v1" (previous behavior, kept for compatibility).
languageoptional string ISO 639-1 code. Defaults to "en". Text is scored as written by English-trained models (no translation step), and the conversational-event rules cover English only: translate non-English text to English first for reliable results.
agent_last_messageoptional string Your previous message (up to 20,000 characters). Context only: it tells the event rules whether you offered a next step, and support recipes include it in the handoff packet. Never analyzed as the participant's personality.
agent_goaloptional string What your agent is trying to achieve (up to 500 characters). Context only.
explicit_preferencesoptional object Preferences the person stated themselves; they override the inferred style and persist for this participant until changed ("" clears a key). Up to 12 lowercase snake_case keys (max 40 characters), values up to 200 characters. Axis keys: thinking (analytical | holistic | balanced), information (detail | big_picture | balanced), orientation (goal | path | balanced), reference (internal | external | balanced), framing (opportunity | safety | balanced). Any other key is passed through as a stated instruction, for example {"length": "short"}.
capabilitiesoptional object support-v2. What your deployment can actually do: { "actions": [...], "human_route"?: string }. actions (required, up to 8) from prepare_summary, transfer_to_human, request_callback, assign_owner; human_route (up to 300 characters) is a factual way to reach a person that your agent may share. Persists for the participant until sent again.
action_resultsoptional array of object support-v2. Results of your own action tools since your last call, up to 5: { "action", "status": "succeeded" | "failed" | "unavailable", "reference"?, "detail"? }. These are the only evidence that a handoff, callback or owner assignment happened; report failures too.
deadline_msoptional integer Per-turn inference deadline, 500–30,000. Defaults to 8,000. On timeout the result is marked stale or unavailable, never presented as fresh.
include_textoptional boolean Add text: a compact plain-text rendering of the result (the text block the MCP tool returns).
include_debugoptional boolean Add debug: operator data (numeric reads, baseline, recipe). Off by default.

Example request

curl
curl https://api.millionways.ai/v2/behavioral-context \
  -H "Authorization: Bearer mw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv-4711",
    "participant_id": "customer",
    "turn_id": "t3",
    "message": "I have explained this twice now. Who is actually responsible for fixing this? I need a straight answer before my meeting tomorrow.",
    "agent_last_message": "Could you describe the issue once more?",
    "recipe_id": "general-v2"
  }'

Response 200

Illustrative and abbreviated.

JSON
{
  "object": "behavioral_context",
  "context_id": "ctx_xxxxxxxxxxxxxx",
  "conversation_id": "conv-4711",
  "participant_id": "customer",
  "turn_id": "t3",
  "turn_index": 3,
  "created": 1791915609,
  "versions": { "schema": "1.2.0", "recipe": "[email protected]", "skill": "[email protected]", "model": "thorsten-4" },
  "state": {
    "resource": "pressured",
    "undertone": null,
    "read": "Under pressure: urgent, narrowed focus, high expectations.",
    "observed_turn_id": "t3",
    "status": "current",
    "evidence": { "scope": "latest_turn", "turn_ids": ["t3"], "chars": 139, "new_share": 1, "sufficiency": "medium", "age": { "turns": 0, "seconds": 0 } },
    "attribution": "self",
    "note": "..."
  },
  "events": [
    { "type": "owner_requested", "strength": "strong", "evidence": "Who is actually responsible for fixing this?", "context": [], "rule": "events.owner" }
  ],
  "preferences": {
    "status": "provisional",
    "basis": { "reads": 2, "chars": 310 },
    "axes": {
      "orientation": { "style": "goal", "strength": 72, "source": "inferred" }
    },
    "driver": { "style": "power", "need": "...", "source": "inferred" },
    "explicit": {}
  },
  "changes": {
    "baseline": { "status": "warming_up", "observations": 1, "required": 2 },
    "items": []
  },
  "guidance": {
    "focus": "...",
    "recommendation": "Name who owns the fix and what happens next, in two or three short sentences.",
    "reasons": ["..."],
    "do": ["..."],
    "avoid": ["Asking them to repeat the problem."],
    "structure": "...",
    "check_in": null,
    "basis": ["event", "state"]
  },
  "quality": {
    "status": "fresh",
    "inference": "completed",
    "evidence": { "turn_chars": 139, "window_chars": 139, "window_turns": 1, "new_share": 1, "total_chars": 310, "reads": 2, "sufficiency": "medium" },
    "age": { "turns": 0, "seconds": 0 },
    "baseline_updated": true,
    "warnings": ["provisional_preferences"],
    "note": "..."
  },
  "provenance": { "analysis_id": "an_xxxxxxxxxxxxxx", "window_turn_ids": ["t3"], "rules": ["..."] },
  "timing": { "total_ms": 452.1, "inference_ms": 448.2, "engine_ms": 1.2, "store_ms": 2.7, "deadline_ms": 8000 }
}

Result fields

FieldDescription
eventsWhat the participant just did, from explicit rules over their words: possible_disengagement, pause_requested, re_engagement, next_step_accepted (they agreed to a step you offered), next_step_requested (they asked for a step, or a different one), owner_requested, human_requested. strength (weak | moderate | strong) says how explicit the wording is, not a probability. Next-step events carry action (callback, email, sms, summary, human, owner, other).
stateHow the participant seems: resource (resourced | engaged | adaptive | pressured | overwhelmed), an optional undertone, and a plain-language read. Check status first: current (read on this message), uncertain (mostly earlier text, or strain attributed to others or a situation), inherited (this message was not read; the state is from observed_turn_id). null until a first read exists.
preferencesCommunication style per axis (thinking, information, orientation, reference, framing), each { style, strength 0–100, source: inferred | explicit }, plus the driver (power | achievement | contact | mixed) and the stated explicit preferences. status: established, provisional (early read; hold loosely) or unavailable.
changesShifts versus the participant's own baseline (basis: "baseline") or recoveries since their last read (basis: "previous") in pressure, guardedness or composure. baseline.status is warming_up until enough reads exist.
guidanceThe next-reply recommendation with conflicts already resolved (explicit preferences and policy first, then events, then inferred signals): recommendation, focus, do, avoid, structure, an optional check_in question, and reasons.
qualitystatus: fresh (a read was made on new words this turn), stale (an earlier read is shown; see age), insufficient (too little text yet), unavailable. inference: completed | timeout | failed | incomplete | skipped | replayed | disabled. evidence counts characters and reads; it is not a probability that the read is correct.
policySupport recipes only. action (continue | adapt | de_escalate | handoff_to_human), instructions, say, risk (score, band, trend), handoff, and in support-v2 also engagement, resolution and routing (request, recommended route, host-reported execution, factual handoff summary).
context_id, versions, provenance, timingOperator fields for logging and support. Never show them to the participant.
text, debugOnly with include_text / include_debug.

Retries and concurrency

Common errors

StatuscodeWhen
400invalid_requestA field is missing or invalid, or recipe_id is unknown. param names the field.
403insufficient_permissionsAPI key lacks the analyze permission.
409turn_already_processedThe turn_id belongs to an earlier turn of this participant.
409participant_busyAnother request for this participant is still running. Retry after Retry-After.
500behavioral_context_failedUnexpected server error. Quote the request_id.

Runtime skill — GET /v2/behavioral-context/skill

Public (no key needed). Returns the compact runtime skill an agent needs to act on a result, plus the available recipes. Load it once per agent session, not per turn. It is also available as readRoomSkill in GET /v2/skill-package.

JSON
{
  "object": "skill",
  "id": "read-room",
  "version": "1.2.0",
  "schema_version": "1.2.0",
  "recipes": [
    { "id": "general-v2", "version": "2.1.0", "title": "General conversation", "description": "..." }
  ],
  "skill": "## MILLIONWAYS READ_ROOM — BEHAVIORAL CONTEXT SKILL ..."
}
POST /v2/escalation-risk permission: analyze stable

Escalation risk #

Score one customer turn of a live conversation: is this interaction moving toward complaint, conflict, churn or regulatory risk, and should a human step in? Returns an escalation risk score from 0 to 100 with a band, the trend across turns and a recommended action; a human-understanding read of the customer (communication preferences, core need, current state, calibration questions); a playbook for the agent's next reply; and, when risk is high, a handoff packet for the human. The score combines Thorsten-4 signals from the customer's recent messages with deterministic escalation markers in the latest message. The same logic backs the MCP tool assess_escalation_risk.

Pass a stable session_id per conversation so the trajectory builds up. Sessions expire 24 hours after the last turn. Without a session, pass previous_customer_messages instead.

⚠ A moment-state estimate, not a verdict. Escalation risk describes the interaction, derived from the customer's own words. It is not a trait, a diagnosis or a deception measure. Never quote the score, band or any psychological read to the customer, and never use it to take adverse action against them.

Request body

FieldTypeDescription
customer_messagerequired string The customer's latest message, verbatim (1–20,000 characters). Works on short chat turns; longer text gives a more confident read.
session_idoptional string or null Stable ID for this conversation, 1–128 characters: letters, digits, . _ : -. Reuse it on every turn. Strongly recommended.
previous_customer_messagesoptional array of string Fallback when you cannot keep a session: the customer's earlier messages, oldest first (up to 50, each up to 20,000 characters). Ignored when the session already has history.
agent_last_messageoptional string What the agent said just before this message. Not scored; included in the handoff packet.
languageoptional string ISO 639-1 code. Defaults to "en". Text is scored as written (no translation step): the Thorsten-4 read is English-trained, and the escalation markers cover English and core German phrases. Translate other languages to English first for reliable results.
channeloptional string "chat" (default), "email" or "voice_transcript".
reset_sessionoptional boolean Start a fresh trajectory for this session_id with this message.
include_guidanceoptional boolean Add guidance: the escalation and human-understanding guidance text that tells an agent how to act on the result. Defaults to false here (the MCP tool defaults to true). The same text is at GET /v2/escalation-risk/skill.

Bands and actions

Scorebandrecommended_action
below 35lowcontinue
35 to below 55elevatedadapt
55 to below 75highde_escalate
75 and abovecriticalhandoff_to_human

Explicit statements override the score: an explicit request for a person always gives handoff_to_human; a legal or regulatory threat gives at least de_escalate; and risk that stays high for three consecutive turns without falling moves de_escalate to handoff_to_human.

Example request

curl
curl https://api.millionways.ai/v2/escalation-risk \
  -H "Authorization: Bearer mw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_message": "This is the third time I am contacting you about the same problem. Nobody has called me back. I am getting really frustrated.",
    "session_id": "conv-4711",
    "agent_last_message": "I have reset the line from our side. Could you try again tonight?",
    "channel": "chat"
  }'

Response 200

Illustrative and abbreviated.

JSON
{
  "object": "escalation_assessment",
  "session_id": "conv-4711",
  "turn": 3,
  "created": 1791915609,
  "channel": "chat",
  "escalation_risk": {
    "score": 58.4, "band": "high", "trend": "rising", "confidence": 0.85,
    "delta_from_previous": 17.2, "mode": "confrontation", "recovering": false
  },
  "recommended_action": "de_escalate",
  "action_reasons": ["Risk is high. Run the de-escalation protocol and offer a human proactively; do not keep problem-solving as if nothing is wrong."],
  "flags": ["repeat_contact", "rising"],
  "components": {
    "affective_strain": 78.5, "regulation_deficit": 94.0, "conflict_orientation": 75.7,
    "implicit_risk": 74.1, "linguistic_markers": 55.1, "trajectory_momentum": 77.2
  },
  "evidence": {
    "lexical": { "categories": ["repeat_contact", "complaint_intensity"], "hits": { "repeat_contact": ["third time"], "complaint_intensity": ["frustrated"] }, "word_count": 24, "shouting": false },
    "thorsten": { "negative_affect": 75.4, "pressure_state": 58.7 },
    "thorsten_used": true,
    "thorsten_window_chars": 412
  },
  "human_understanding": {
    "profile_confidence": "high",
    "communication_preferences": { "orientation": { "style": "goal", "strength": 89, "read": "..." } },
    "core_need": { "driver": "power", "need": "...", "give": ["..."], "never": ["..."] },
    "current_state": { "resource": "pressured", "read": "..." },
    "under_pressure": "...",
    "regulation_needs": ["..."],
    "calibration_questions": [ { "ask": "...", "purpose": "...", "ask_when": ["low", "elevated"] } ],
    "playbook": { "open_with": "...", "structure": "...", "do": ["..."], "avoid": ["..."] }
  },
  "agent_playbook": { "now": ["..."], "say": ["..."], "avoid": ["..."], "status_line": "..." },
  "handoff_packet": {
    "summary": "...", "customer_state": "...", "what_they_need": "...", "open_with": "...",
    "what_to_avoid": ["..."], "flags": ["repeat_contact", "rising"], "trajectory": [],
    "last_customer_message": "...", "agent_last_message": "..."
  },
  "trajectory": [
    { "turn": 1, "score": 22.1, "band": "low", "action": "continue" },
    { "turn": 2, "score": 41.2, "band": "elevated", "action": "adapt" },
    { "turn": 3, "score": 58.4, "band": "high", "action": "de_escalate" }
  ],
  "disclaimer": "Escalation risk is a moment-state estimate about the interaction ..."
}

Result fields

FieldDescription
escalation_riskscore (0–100), band, trend (rising | flat | falling | insufficient_history), confidence (0–1; reflects how much customer text was analyzed, the session history, and whether Thorsten-4 was available; not a probability that the score is right), delta_from_previous, mode (confrontation | withdrawal | mixed), and recovering (risk dropped and the customer responded positively).
recommended_action, action_reasonsWhat the agent should do now (continue | adapt | de_escalate | handoff_to_human) and why.
flagsTriggers such as explicit_human_request, bot_frustration, legal_or_regulatory_threat, churn_threat, hostility, repeat_contact, urgency, disengagement, helplessness, shouting, sustained_high, rising, rising_fast, recovering.
componentsThe score's inputs, each 0–100: affective_strain, regulation_deficit, conflict_orientation, implicit_risk (from Thorsten-4), linguistic_markers (from the latest message), trajectory_momentum (50 = flat).
evidenceThe matched escalation markers (lexical), the Thorsten-4 signals used (thorsten; null when unavailable), and how much customer text was analyzed.
human_understandingOperator-facing read of the customer: communication_preferences (five axes, each { style, strength, read }), core_need, current_state, under_pressure, regulation_needs, calibration_questions (each with the bands in which to ask it; never in critical), and a playbook.
agent_playbookFor the next reply: now, say, avoid, and an operator status_line (not for the customer).
handoff_packetPresent when the action is de_escalate or handoff_to_human, otherwise null: summary, customer state, what they need, how to open, what to avoid, flags, trajectory, and the last messages.
trajectoryOne { turn, score, band, action } per turn so far.
guidanceOnly with include_guidance: true.

Common errors

StatuscodeWhen
400invalid_requestcustomer_message is missing or empty, a field has the wrong type or length, or session_id has invalid characters. param names the field when known.
403insufficient_permissionsAPI key lacks the analyze permission.
500escalation_failedUnexpected server error. Quote the request_id.

Guidance text — GET /v2/escalation-risk/skill

Public (no key needed). Returns the guidance text that tells an agent how to act on an assessment, so you can put it in your agent's system prompt once: { "version": "v1", "escalationSkill": "..." }. It is also available as escalationSkill in GET /v2/skill-package.

GET /v2/escalation-risk/sessions/:session_id permission: analyze stable

Escalation session #

Supervisor view of a session tracked by Escalation risk: the risk trajectory turn by turn, the current band, trend and action, the peak score, the latest human-understanding read, and the handoff packet if a human should step in. It scores nothing new. The MCP tool get_escalation_session returns the same view.

Response 200

Abbreviated. created, updated and turns[].ts are Unix milliseconds.

JSON
{
  "object": "escalation_session",
  "session_id": "conv-4711",
  "created": 1791915400000,
  "updated": 1791915609000,
  "channel": "chat",
  "language": "en",
  "turn_count": 3,
  "current": { "score": 58.4, "band": "high", "action": "de_escalate", "trend": "rising", "mode": "confrontation", "flags": ["repeat_contact", "rising"] },
  "peak_score": 58.4,
  "trajectory": [ { "turn": 3, "score": 58.4, "band": "high", "action": "de_escalate" } ],
  "turns": [
    { "turn": 3, "ts": 1791915609000, "score": 58.4, "band": "high", "action": "de_escalate", "mode": "confrontation",
      "flags": ["repeat_contact", "rising"], "components": {}, "preview": "This is the third time I am contacting you about the same problem…" }
  ],
  "human_understanding": {},
  "handoff_packet": {},
  "disclaimer": "..."
}

human_understanding is null until the session has a Thorsten-4 read; handoff_packet is null unless the last action was de_escalate or handoff_to_human. Message previews are truncated to 240 characters. The session keeps the last 60 turns.

Reset — DELETE /v2/escalation-risk/sessions/:session_id

Deletes the session. Returns 200 with { "object": "escalation_session", "session_id": "conv-4711", "deleted": true }; deleted is false when no such session existed.

Common errors

StatuscodeWhen
400invalid_requestsession_id has invalid characters or length.
403insufficient_permissionsAPI key lacks the analyze permission.
404session_not_foundGET only: no session with that ID in your organization (sessions expire 24 hours after the last turn).
500escalation_session_failedUnexpected server error. Quote the request_id.

POST /mcp permission: analyze stable

MCP server #

millionways ships a hosted Model Context Protocol server. It exposes behavioral analysis as tools that AI agents and LLM applications can call directly — Claude, agent platforms, MCP gateways, and any other MCP-compatible client. Connect once and every tool below becomes available to your agent, with no REST integration code.

Endpoint

https://api.millionways.ai/mcp

The transport is Streamable HTTP in stateless mode: every JSON-RPC message (or batch) is an independent POST, with no session ID and no server-sent event stream to open. GET and DELETE return 405 with Allow: POST. The server supports MCP protocol versions up to 2025-11-25 and identifies itself as millionways version 0.7.0. The endpoint lives at the root path /mcp, not under the /v2 prefix. Nothing needs to be installed locally.

Authentication

Two ways to authenticate. Either way the credential must carry the analyze permission.

API key. The same keys and headers as the REST API (see Authentication):

HTTP
Authorization: Bearer mw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Gateways and agent platforms that send the key in an x-api-key, api-key, api_key or x-authorization header, or as a raw Authorization value without Bearer, are supported: paste the raw key into the platform's API-key field.

OAuth 2.1. MCP clients that implement the standard MCP authorization flow can sign users in instead of using a pre-shared key. The authorization server is millionways' WorkOS AuthKit instance at https://pleasing-raindrop-26.authkit.app. A 401 from /mcp carries a WWW-Authenticate header pointing to the Protected Resource Metadata, served at /.well-known/oauth-protected-resource and /.well-known/oauth-protected-resource/mcp. The resource, and the required token audience, is https://api.millionways.ai/mcp.

OAuth access tokens are accepted on /mcp only. The REST endpoints take API keys; an OAuth token sent to them will get 401 invalid_oauth_token once this rule is enforced. It is currently in monitoring mode: nothing is rejected yet.

ℹ OAuth needs an enabled organization. There is no self-serve sign-up: millionways must enable your organization before its users can sign in. Contact millionways to set this up. Token problems return 401 with invalid_oauth_token, missing_org_claim or organization_not_provisioned.

Browser origins and rate limits

Available tools

Eleven tools. evaluate_candidate is enabled per organization: contact millionways to enable it. Organizations without it see the other ten, and a call to it returns a tool error saying it is not enabled. While this rolls out, every organization still sees all eleven. GET /v2/mcp/tools (same credentials as /mcp) returns the names of the tools your key can use, as {"tools": [{"name": "read_room"}, ...]}. Every tool publishes MCP tool annotations (a title plus readOnlyHint, destructiveHint, idempotentHint and openWorldHint). Only get_escalation_session is read-only: each profile tool call stores an analysis record in your organization, and read_room / assess_escalation_risk update the conversation's state. Every tool except get_escalation_session also accepts an optional language (ISO 639-1, default "en"). Text is scored as written by English-trained models, with no translation step, so pass English text for reliable results.

Live conversations

ToolRequired inputWhat it does
read_roomconversation_id, participant_id, turn_id, messageBehavioral context for live conversations. Call once per participant message, before replying: conversational events in the message, how the participant seems, how they like to be communicated with, what changed, and one resolved recommendation for the next reply. Same inputs and result as POST /v2/behavioral-context, plus include_skill (set it on the first call to receive the runtime skill once). Returns native structured content, validated by a published outputSchema, plus a short text rendering.
assess_escalation_riskcustomer_message (and a stable session_id, strongly recommended)Escalation risk and human understanding for live customer conversations. Call on every customer message before replying: risk score with band, trend and a recommended action (continue, adapt, de_escalate, handoff_to_human), a read of the customer with gentle calibration questions, a playbook for the next reply, and a handoff packet when risk is high. Same as POST /v2/escalation-risk, except that include_guidance defaults to true.
get_escalation_sessionsession_idSupervisor view of a session tracked by assess_escalation_risk: trajectory turn by turn, current band, trend and action, peak, the latest read of the customer, and the handoff packet. Scores nothing new. Same as GET /v2/escalation-risk/sessions/:session_id.

Behavioral profiles

ToolRequired inputWhat it does
analyze_textcontentGeneric behavioral profile of the author of any text (journal entry, social post, writing sample, ambiguous email): what drives them, how they think and decide, how they handle pressure. The open-ended entry point when no more specific tool fits.
evaluate_candidatecontentHiring read of a writing sample (cover letter, work email, interview transcript, written assessment): role fit, leadership readiness, pressure behavior, likely failure mode, and a recommendation. Optional role_context. Enabled per organization.
team_fitperson_a_content, person_b_contentTeam fit between two people from a writing sample each: interaction pattern, complementary strengths, likely friction, and one recommendation. Optional labels and team_context.
analyze_spokespersoncontentSpokesperson, influencer or brand-ambassador fit from their own words: the trust they build, the audience they resonate with, their authentic message style, and where they create resistance. Optional brand_context.
analyze_customer_messagecontentReads a customer's own message (support email, complaint, enquiry, account thread) and returns guidance for a reply that resonates: what builds or erodes trust, what to say and what to avoid. Optional relationship_context.
sales_outreach_strategybuyer_contentTurns a prospect's own messages into a sales strategy: what drives the buyer, the objections they specifically are likely to raise, and the next outreach message written, or the seller's draft rewritten, to match. Optional seller_draft and deal_context.
seller_buyer_fitseller_content, buyer_contentThe dynamic between a specific seller and buyer from a sample of each: where their styles collide, where they build trust, and what the seller should adapt next. Asymmetric: the seller adapts. Optional labels and deal_context.
compare_peopleperson_a_content, person_b_content, environmentTwo-person comparison through the scenario environment you choose: talent_leadership, consumer_brand_behavior, client_relationships, care_matching or legal_testimony. Optional labels and comparison_context.

Built-in interpretation

The eight profile tools embed the millionways behavioral interpretation skill ahead of the profile data, so the calling LLM translates Thorsten scores into plain behavioral language instead of echoing raw numbers. assess_escalation_risk includes its guidance text unless you pass include_guidance: false, and read_room returns its runtime skill when you pass include_skill: true. The same texts are public for REST integrators: /v2/skill-package, /v2/behavioral-context/skill and /v2/escalation-risk/skill.

A tool that fails returns a normal result with isError: true and a short message; internal error details are never included.

Connecting a client

Clients that connect to a remote MCP server over Streamable HTTP need two values: the server URL https://api.millionways.ai/mcp and your API key in a header.

Claude Code (command line):

shell
claude mcp add --transport http millionways https://api.millionways.ai/mcp \
  --header "Authorization: Bearer mw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Claude Code project file (.mcp.json):

JSON
{
  "mcpServers": {
    "millionways": {
      "type": "http",
      "url": "https://api.millionways.ai/mcp",
      "headers": {
        "Authorization": "Bearer mw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor (~/.cursor/mcp.json or the project's .cursor/mcp.json):

JSON
{
  "mcpServers": {
    "millionways": {
      "url": "https://api.millionways.ai/mcp",
      "headers": {
        "Authorization": "Bearer mw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
✦ Tools need the person's own words, verbatim. Profile tools should get at least 200 characters of text the person actually wrote or said (longer is better); summaries or descriptions of a person do not carry the behavioral signal the model reads. read_room and assess_escalation_risk work on short chat turns.

Result schema #

A completed analysis returns the object documented below. All numeric scores are illustrative; real ranges and structure are described in the constraint columns.

Six core systems

Every analysis projects the input onto six core behavioral systems. Each maps to a top-level object in the response.

Motives
motives
Power, achievement, and contact drives, plus the dominant motive.
Cognition
cognition
Detail/holistic, internal/external, analytical, goal/path orientation.
Affect
affect
Approach/avoidance, positive/negative valence, behavioral level distribution.
Self-regulation
regulation
Self-motivation, self-relaxation, action orientation, volitional efficiency, stress resilience.
PSI macrosystems
systems
Extension memory, object recognition, intention memory, intuitive behavior, plus dominant system and personality style.
Insights and descriptions
insights, descriptions
Narrative summary, strengths, development areas, and per-dimension descriptions used for interpretation.

Top-level object

FieldTypeStabilityDescription
idstringstableUnique analysis ID, prefixed an_.
objectstringstableAlways "analysis".
createdintegerstableUnix timestamp (seconds) when the analysis was produced.
modelstringstableModel identifier, for example "thorsten-4".
motivesobjectstableMotive scores, dominant motive, prediction class, and confidence map.
cognitionobjectstableCognitive style dimensions.
affectobjectstableAffect, valence, and behavioral level distribution.
regulationobjectstableSelf-regulation capacities. Present when options.include_psi is true (the default).
systemsobjectstablePSI macrosystem activations, dominant system, and style mapping. Present when options.include_psi is true (the default).
insightsobjectstableSummary, strengths, and development areas. Present when options.include_insights is true (the default).
usageobjectstableUsage metrics: character count and model, plus audio_seconds for audio.
transcript, analyses, tone_analysis, dissonanceobject / arraystableAudio results only. See Analyze audio.
descriptionsobjectstableNarrative descriptions for motives, affect, cognition, and behavioral levels. Only in the synchronous POST /v2/analyze response; not in polled job results.

Detailed field map

FieldTypeConstraintsDescription
motives
motives.powernumber0–100Power motive strength.
motives.achievementnumber0–100Achievement motive strength.
motives.contactnumber0–100Contact motive strength.
motives.dominantstringenumOne of "power", "achievement", "contact".
motives.predictionstring—Top-1 prediction class label from the underlying classifier.
motives.confidence_scoresobject—Per-class confidence map. Keys include "0" and pairs such as "M-3", "L-2", "A-1" identifying motive level cells. Values are floats in [0, 1].
cognition
cognition.detailnumber0–100Detail orientation score.
cognition.realizationnumber0–100Realization orientation score (complement of detail).
cognition.analyticalnumber0–100Analytical orientation score.
cognition.holisticnumber0–100Holistic orientation score.
cognition.internalnumber0–100Internal orientation score.
cognition.externalnumber0–100External orientation score.
cognition.goalnumber0–100Goal orientation score.
cognition.pathnumber0–100Path orientation score.
affect
affect.approachnumber0–100Approach orientation score.
affect.avoidancenumber0–100Avoidance orientation score.
affect.positivenumber0–100Positive affect score.
affect.negativenumber0–100Negative affect score.
affect.levelnumber1.0–5.0Behavioral level (continuous).
affect.level_distributionobject—Distribution over level1 through level5; values sum to 100.
regulation
regulation.self_motivationnumber0–100Capacity for self-generated motivation.
regulation.self_relaxationnumber0–100Capacity for self-driven downregulation.
regulation.action_orientation_failurenumber0–100Action orientation after failure events.
regulation.action_orientation_decisionnumber0–100Action orientation when initiating a decision.
regulation.volitional_efficiencynumber0–100Volitional efficiency score.
regulation.stress_resiliencenumber0–100Stress resilience score.
systems (PSI macrosystems)
systems.extension_memorynumber0–100Extension memory activation.
systems.object_recognitionnumber0–100Object recognition activation.
systems.intention_memorynumber0–100Intention memory activation.
systems.intuitive_behaviornumber0–100Intuitive behavior activation.
systems.dominantstringenumDominant system key.
systems.personality_stylestringenumMapped style: agreeable, self_determined, conscientious, independent.
systems.style_scoresobject—Per-style scores keyed by the same enum values.
insights / usage
insights.summarystring—Narrative summary of the profile.
insights.strengthsarray of string—Key strengths surfaced from the profile.
insights.development_areasarray of string—Suggested development areas.
usage.charactersinteger≥ 0Character count of the processed input.
usage.modelstring—Model used for usage accounting.
descriptionsobject—Container with narrative objects for motives, affect, cognition, and behavioral levels. See the table below for interpretation.

Interpretation guide

The descriptions object is generated using the interpretation rules below. Each cell maps a profile dimension and intensity band to a plain-English meaning suitable for client-facing reporting.

DimensionBandMeaning
Achievement MotiveDominantStrongly driven by mastery, excellence, and continuous improvement, with very high standards for performance.
Achievement MotiveModerateReliably goal-oriented and growth-focused, balancing quality with pragmatism rather than perfectionism.
Achievement MotiveNoticeableCares about achievement but often prioritizes relationships, flexibility, or well-being over relentless performance.
Power MotiveDominantStrongly motivated to influence, lead, persuade, and shape outcomes through authority or impact.
Power MotiveModerateNaturally inclined to guide and inspire others, with leadership energy that is confident but more balanced.
Power MotiveNoticeableCan influence and lead when needed, but tends to do so selectively and with quieter authority.
Contact MotiveDominantDeeply driven by closeness, trust, and emotionally meaningful relationships.
Contact MotiveModerateWarm, connection-oriented, and strong at rapport-building, with a preference for harmony and reciprocity.
Contact MotiveNoticeableValues relationships, but is more selective and independent in where emotional energy is invested.
Approach / AvoidanceHigh ApproachMoves toward challenges with optimism, flexibility, and resilient goal pursuit.
Approach / AvoidanceBalancedCombines ambition with caution, weighing opportunities and risks before acting.
Approach / AvoidanceHigh AvoidanceMore likely to protect against pressure, threat, or failure through hesitation, withdrawal, or overthinking.
External / InternalHigh ExternalEnergized by action, people, and outside feedback, with a naturally expressive and outward-facing style.
External / InternalBalancedBlends social engagement with reflection, shifting between interaction and depth as needed.
External / InternalHigh InternalMore self-directed, reflective, and inwardly anchored, preferring depth and authenticity over surface interaction.
Detail / HolisticHigh DetailFocused on precision, structure, and getting specifics right.
Detail / HolisticBalancedAble to manage both specifics and the broader strategic picture.
Detail / HolisticHigh HolisticNaturally thinks in systems, patterns, and long-range context rather than isolated details.
Intuitive / AnalyticalHigh IntuitiveQuickly reads patterns, unspoken needs, and emerging possibilities.
Intuitive / AnalyticalBalancedIntegrates instinct and logic, using both feel and structure in decision-making.
Intuitive / AnalyticalHigh AnalyticalRelies on logic, evidence, and structured evaluation to make decisions.
Goal / PathHigh GoalStrongly oriented toward outcomes, targets, and measurable achievement.
Goal / PathBalancedCares about both reaching the objective and the quality of the process used to get there.
Goal / PathHigh PathMore motivated by the journey, learning, and relationship-building process than by the end result alone.
Self-MotivationHighEasily generates internal energy and enthusiasm to tackle difficult, boring, or unappealing tasks.
Self-MotivationBalancedCapable of pushing through necessary tasks but may occasionally need external deadlines or incentives.
Self-MotivationLowStruggles to find the drive for uninteresting tasks, often relying heavily on external pressure to start.
Self-RelaxationHighQuickly calms down and recovers from stress, maintaining composure and focus under pressure.
Self-RelaxationBalancedGenerally manages stress well but requires active strategies or dedicated time to fully decompress.
Self-RelaxationLowFinds it difficult to turn off anxiety or tension, often carrying stress and physical tension long after the event.
Action Orientation (Failure)HighRapidly bounces back from setbacks, focusing on future solutions rather than dwelling on past mistakes.
Action Orientation (Failure)BalancedProcesses setbacks thoughtfully before moving on, balancing necessary reflection with forward momentum.
Action Orientation (Failure)LowTends to ruminate on mistakes or negative feedback, making it harder to let go and move past setbacks.
Action Orientation (Decision)HighSwiftly moves from planning to execution, making decisions and initiating action without unnecessary hesitation.
Action Orientation (Decision)BalancedWeighs options carefully but ultimately takes decisive action within a reasonable timeframe.
Action Orientation (Decision)LowProne to procrastination or over-analyzing, finding it difficult to initiate the very first step of a task.
Volitional EfficiencyHighHighly effective at translating intentions into actions smoothly, without wasting mental energy.
Volitional EfficiencyBalancedGenerally productive and steady, though sustaining focus on highly complex tasks takes some deliberate effort.
Volitional EfficiencyLowFrequently expends high mental effort to stay on track, leading to faster cognitive fatigue and burnout.
Stress ResilienceHighRemains highly stable, adaptable, and functional even in highly demanding, chaotic, or unpredictable situations.
Stress ResilienceBalancedHandles moderate pressure effectively but may feel the strain and require support during prolonged crises.
Stress ResilienceLowEasily overwhelmed by unexpected demands or heavy pressure, requiring a supportive environment to function best.
Ext. Memory (Self-Determined)HighDeeply anchored in authentic values, naturally seeing the big picture and drawing on a wealth of personal experience.
Ext. Memory (Self-Determined)BalancedConnects well with inner values while remaining practical and adaptable to the immediate situation at hand.
Ext. Memory (Self-Determined)LowMay lose touch with the broader context or personal needs when faced with sudden stress or rigid rules.
Obj. Recognition (Conscientious)HighHighly alert to errors, discrepancies, and fine details, ensuring rules and high standards are strictly met.
Obj. Recognition (Conscientious)BalancedValues accuracy and quality control but avoids getting completely bogged down in rigid perfectionism.
Obj. Recognition (Conscientious)LowTends to overlook finer details or strict rules, preferring a more relaxed, improvisational, or broad approach.
Intention Memory (Independent)HighStrongly analytical and disciplined, holding firm to long-term plans and executing them methodically and logically.
Intention Memory (Independent)BalancedMaintains clear goals and logical plans while allowing some flexibility for changes in the environment.
Intention Memory (Independent)LowPrefers spontaneity over strict planning, often shifting goals based on immediate circumstances or new information.
Intuitive Behavior (Agreeable)HighActs spontaneously and smoothly, effortlessly adapting to social contexts, reading the room, and going with the flow.
Intuitive Behavior (Agreeable)BalancedBlends natural, go-with-the-flow responsiveness with occasional deliberate planning and boundary-setting.
Intuitive Behavior (Agreeable)LowPrefers deliberate, calculated actions and predictability over relying on gut feelings or spontaneous interactions.
Behavioral Levels—Levels combine with the dominant motive to reveal how a person pursues their goals, or can be read independently as overall resilience and flow.
Behavioral LevelsLevel 1Intrinsically aligned, intuitive, energized, and operating in a natural flow state.
Behavioral LevelsLevel 2Highly satisfied and creative, but more fueled by external standards, recognition, and achievement.
Behavioral LevelsLevel 3Generally resilient and functional, though emotionally affected by setbacks and adapting through reflection.
Behavioral LevelsLevel 4Under intense pressure, urgent, self-questioning, and striving to maintain control while solving hard problems.
Behavioral LevelsLevel 5More weighed down by negative emotion, hesitation, low energy, and risk-avoidance, making initiative and creativity harder.
Power MotiveLevel 1Effortlessly charismatic and inspiring, naturally drawing others to their vision while remaining unfazed by criticism.
Power MotiveLevel 2Thrives on leading and motivating groups, using challenges and the pursuit of status to fuel a dynamic and persuasive energy.
Power MotiveLevel 3Deeply values having a respected voice, actively shaping circumstances to guide others while using criticism as a tool for personal growth.
Power MotiveLevel 4Urgently driven to influence and direct others, often employing assertive tactics but prone to impatience and strong emotional reactions to criticism.
Power MotiveLevel 5Desires to make an impact but feels paralyzed by self-doubt and criticism, requiring a highly safe and supportive environment to share their voice.
Achievement MotiveLevel 1Intrinsically fueled by the joy of mastering demanding goals, viewing daunting challenges as exciting opportunities rather than sources of stress.
Achievement MotiveLevel 2Highly motivated by progress, excellence, and recognition, tackling challenges with enthusiasm and quickly pivoting when mistakes occur.
Achievement MotiveLevel 3Finds deep satisfaction in achieving goals, maintaining a steadfast and resilient focus even when momentarily disrupted by stress or mistakes.
Achievement MotiveLevel 4Relentlessly pushes for progress and solutions, often overextending themselves and experiencing irritation or self-criticism when facing obstacles.
Achievement MotiveLevel 5Holds high standards but currently feels overwhelmed and energetically drained, with a fear of failure making it difficult to take decisive action.
Contact MotiveLevel 1Effortlessly forms profound, authentic bonds, radiating warmth and empathy while remaining entirely unbothered by the prospect of rejection.
Contact MotiveLevel 2Naturally builds deep, trusting relationships and enthusiastically welcomes new connections, recovering quickly from occasional social setbacks.
Contact MotiveLevel 3Intentionally cultivates deep, enduring bonds, drawing on high empathy to support others while feeling rejection deeply before bouncing back.
Contact MotiveLevel 4Craves meaningful connections but has limited social energy, fiercely protecting a tight inner circle while finding broader social demands draining.
Contact MotiveLevel 5Deeply values strong bonds but is highly sensitive to rejection, often withdrawing into a small, safe social circle to conserve emotional energy.

Error codes #

Stable, machine-readable values returned in error.code. Branch on these rather than error.message.

HTTPcodeDescription
400invalid_jsonThe request body is not valid JSON.
400invalid_requestThe request failed validation. param names the field when known.
400missing_required_fieldA required field is absent.
400invalid_field_typeA field has the wrong JSON type.
400invalid_field_valueA field is the right type but outside the allowed range or set.
400invalid_enum_valueA field's value is not one of the accepted enum values.
400conflicting_fieldsMutually exclusive fields were both provided.
400file_too_largeAn uploaded file exceeds its size limit.
400unsupported_formatThe uploaded file format is not in the accepted set.
400upload_errorA multipart upload could not be parsed.
400upload_not_foundInterview reference mode: no file exists at the referenced storage location.
400dissonance_requires_tonedissonance=true without tone_analysis=true.
400unknown_modelChat: the requested model is not recognized.
400provider_not_configuredChat: the selected model provider is not available.
401missing_api_keyNo credential header was sent, or the token is empty.
401invalid_api_keyThe supplied key does not exist.
401inactive_api_keyThe key has been deactivated.
401invalid_oauth_tokenAn OAuth access token is invalid, expired, or was not issued for this resource.
401missing_org_claimAn OAuth access token carries no organization.
401organization_not_provisionedThe OAuth user's organization has not been enabled by millionways.
403insufficient_permissionsThe key lacks a permission required by the endpoint.
403insufficient_scopeThe key lacks the scope required by the endpoint.
403gcs_uri_forbiddenA storage URI points outside your organization's upload prefix.
403origin_not_allowed/mcp: the browser Origin is not allow-listed (monitoring only for now).
404route_not_foundAuthenticated request to a route that does not exist.
404job_not_foundThe job ID does not exist, has expired, or belongs to a different organization.
404upload_not_foundAn interview upload_ref does not exist, is older than 24 hours, or belongs to another organization.
404person_not_foundThe person ID does not exist or belongs to a different organization.
404analysis_not_foundA referenced analysis does not exist in your organization.
404session_not_foundNo escalation session with that ID (sessions expire 24 hours after the last turn).
404not_foundAny other resource that does not exist.
405method_not_allowedThe method is not supported (for example GET /mcp).
409turn_already_processedRead the room: the turn_id belongs to an earlier turn.
409participant_busyRead the room: another request for the participant is running. Retry after Retry-After.
413payload_too_largeThe request body is too large.
415unsupported_media_typeThe Content-Type is not accepted.
429rate_limit_exceededThe key's per-minute ceiling was exceeded (when enforcement is on).
429daily_quota_exceededThe key's daily quota was exceeded (when enforcement is on).
500internal_errorUnhandled server error.
500inference_errorThe inference worker failed to produce a result.
500llm_errorAn LLM-backed endpoint returned an error.
500invalid_model_outputAn LLM-backed endpoint returned malformed output.
500storage_errorA storage operation failed (503 when the uploaded interview object could not be read).
500db_errorA result could not be stored.
500behavioral_context_failedRead the room failed unexpectedly.
500escalation_failedEscalation risk failed unexpectedly.
500escalation_session_failedAn escalation session could not be read or reset.
503service_unavailableThe service is temporarily unavailable.
503storage_not_configuredUpload storage is not configured for this environment.
503upload_session_errorA direct-to-storage upload session could not be created.

Changelog #

Material changes to the v2 API are recorded here. Additive changes (new optional parameters, new response fields) are noted but do not require client updates.

Unreleased