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:
- interview transcripts
- meeting recordings
- earnings call transcripts
- customer conversations
- emails
- chat messages
- social posts
- survey responses
- audio transcripts
- video transcripts
- written assessments
- long-form documents
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:
- creating behavioral profiles from raw communication
- analyzing motivation, cognition, affect, regulation, stress, and operating style
- comparing people, teams, groups, or population segments
- tracking behavioral change over time
- generating scenario-specific behavioral interpretations
- powering matching, compatibility, and relationship-dynamics workflows
- supporting chat experiences grounded in behavioral intelligence
- enabling domain-specific scoring for talent, leadership, investing, customer intelligence, and risk analysis
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:
- Motives: what fundamentally drives the person
- Cognition: how the person processes information and makes decisions
- Affect: emotional direction, energy, and sensitivity
- Regulation: whether strengths remain usable under pressure
- Stress: the current pressure state reflected in the communication sample
- Styles: shorthand operating patterns that summarize how the profile expresses in behavior
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:
- How does this person make decisions under pressure?
- What motivates them when the stakes are high?
- Where are they resilient, and where are they likely to degrade?
- How will they collaborate with another person or team?
- What communication approach is most likely to build trust?
- How might their behavior change as stress, uncertainty, or conflict increases?
- How should this behavioral signal translate into a specific business, product, or risk decision?
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:
- leadership and executive assessment
- team dynamics and collaboration intelligence
- interview and candidate analysis
- coaching and development products
- client relationship intelligence
- sales and customer personalization
- consumer segment analysis
- compatibility and matching systems
- investment research and executive communication analysis
- public safety and escalation-risk workflows
- digital twin and avatar behavior systems
- AI agent governance and behavioral consistency layers
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:
- Submit communication data. Send text, transcripts, audio, or other communication artifacts to the API.
- Generate behavioral intelligence. Thorsten-4 analyzes the input and extracts structured behavioral signals.
- Create or update profiles. Use the output to create people, groups, or longitudinal behavioral records.
- Apply intelligence to your use case. Use the structured output for matching, scoring, interpretation, tracking, or decision support.
- 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:
- raw behavioral scores
- confidence values
- profile summaries
- system-level interpretations
- motive and cognition signals
- affect and regulation patterns
- stress-state indicators
- operating style outputs
- compatibility and matching results
- tracking and change-over-time data
- domain-specific scoring outputs
- chat responses grounded in behavioral intelligence
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 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.
{
"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
-
Read Async jobs and polling to handle
larger inputs that exceed the
sync60 s ceiling. - See the result schema for every field, type, and range.
- Review Errors and retries for the standard error envelope and retry guidance.
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.
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.
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:
| Endpoint | Purpose |
|---|---|
| GET /, GET /v2 | Welcome message with a link to this documentation. |
| GET /health | Service health. |
| GET /v2/docs | This documentation, its logo, and /v2/docs/openapi.yaml. |
| GET /v2/skill-package | The behavioral interpretation skill package (see MCP server). |
| GET /v2/behavioral-context/skill | The runtime skill for Read the room. |
| GET /v2/escalation-risk/skill | The guidance text for Escalation risk. |
| GET /.well-known/oauth-protected-resource | OAuth 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
| Prefix | Purpose |
|---|---|
| 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:
| Requirement | Endpoints |
|---|---|
| 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
- Treat keys as secrets. Store them in a server-side secret store and never embed them in client-side code.
-
Rotate keys by issuing a new key, deploying it, then
deactivating the old one. Deactivated keys return
401 inactive_api_key. -
Each request is attributed to one key and one organization.
Cross-organization access is blocked at the API layer; a
resource owned by another organization returns
404.
Making requests #
Base URL
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.
- Malformed JSON returns
400 invalid_json. - A Content-Type the endpoint does not accept returns
415 unsupported_media_type. - JSON bodies are limited to 1 MiB; larger bodies return
413 payload_too_large. -
Request bodies over 32 MiB are rejected with
413by the hosting front end before they reach the API, so that response may not use the JSON error envelope. This is the effective ceiling for direct multipart uploads.
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.
| Prefix | Resource | Example |
|---|---|---|
| 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:
| Status | Meaning |
|---|---|
| queued | Job created and waiting for a worker. |
| processing | A worker has started; the result is not yet available. |
| completed | The result is available in the result field. |
| failed | The 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.
| Attempt | Wait before next call |
|---|---|
| 1–3 | 1 s |
| 4–6 | 2 s |
| 7+ | 5 s, capped at 30 s |
Recommended timeouts
| Job type | Recommended client timeout |
|---|---|
| Text analysis | 120 s |
| Audio analysis | 15 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.
| Parameter | Type | Default | Description |
|---|---|---|---|
| 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:
{
"object": "list",
"data": [],
"total": 142,
"limit": 20,
"offset": 0
}
data— the array of results for this page.total— the total count across all pages for the current filter.limit/offset— echo of the request parameters.
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.
{
"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.
{
"error": {
"type": "api_error",
"code": "internal_error",
"message": "Internal server error",
"request_id": "8f0c2a4e-5b1d-4c7a-9e3f-2d6b1a0c9e47"
}
}
Error types
| Type | Description |
|---|---|
| invalid_request_error | The request body, parameters or Content-Type are malformed or invalid, or the body is too large. |
| authentication_error | The API key or access token is missing, invalid, or inactive. |
| permission_error | The credential is valid but lacks the required permission or scope, or the request is not allowed from its origin. |
| not_found_error | The resource or route does not exist, or is not accessible to your organization. |
| conflict_error | The request conflicts with the current state (for example a reused turn_id). |
| rate_limit_error | A per-key rate limit or daily quota was exceeded. See Rate limits. |
| overloaded_error | The service or a required upstream (for example Cloud Storage) is temporarily unavailable. |
| api_error | An unexpected server-side error occurred. |
Errors raised before your handler runs
These use the same envelope on every endpoint:
| Status | type / code | When |
|---|---|---|
| 400 | invalid_request_error / invalid_json | The body is not valid JSON. |
| 400 | invalid_request_error / invalid_request | The request failed validation. |
| 401 | authentication_error / missing_api_key, invalid_api_key, inactive_api_key | See Authentication. Unknown paths requested without a key also return 401. |
| 404 | not_found_error / route_not_found | Authenticated request to a route that does not exist. |
| 413 | invalid_request_error / payload_too_large | The body exceeds the size limit. |
| 415 | invalid_request_error / unsupported_media_type | The Content-Type is not accepted by the endpoint. |
| 500 | api_error / internal_error | Unhandled server error. Message "Internal server error", plus request_id. |
Retry guidance
| Status | Retry? | 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 #
Limits apply per API key, in two windows, both in UTC:
| Window | Ceiling | Resets |
|---|---|---|
| Minute | 600 requests per key (default; the same for every key) | At the start of each UTC minute |
| Day | The key's own daily quota, set when the key is issued | 00:00 UTC |
Keys issued without a daily quota are not rate limited at all.
What counts
- Every authenticated
POST,PATCHandDELETEcounts as one request. GET,HEADandOPTIONSare free, so polling jobs and interviews, reads, and streams never count.- On
/mcp, onlytools/callmessages count, one per call (a JSON-RPC batch counts each call).initialize,tools/listand notifications are free.
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:
| Header | Meaning |
|---|---|
| Retry-After | Seconds until the window resets. |
| X-RateLimit-Limit | The ceiling that was exceeded. |
| X-RateLimit-Remaining | Always 0 on a 429. |
| X-RateLimit-Reset | When the window resets, in Unix seconds. |
{
"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
-
Existing endpoint paths and HTTP methods will not change
within the
v2major version. - Existing response fields will not be removed or have their type changed without a major-version bump.
- New optional request parameters and new response fields may be added at any time. Clients should ignore unknown response fields.
-
The wording of
error.messagestrings can change. Branch onerror.codeand HTTP status instead.
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.
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
| Field | Type | Description |
|---|---|---|
| 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 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
{
"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
| Status | code | When |
|---|---|---|
| 400 | missing_required_field | content is missing, empty, or not a string. |
| 400 | invalid_field_type | language or webhook_url is not a string. |
| 400 | invalid_enum_value | mode is not "sync" or "async". |
| 401 | missing_api_key / invalid_api_key | API key missing or invalid. |
| 413 | payload_too_large | The JSON body exceeds 1 MiB. |
| 500 | inference_error | Sync mode only: the worker failed during analysis. |
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
-
Accepted formats:
mp3,wav,m4a,webm. The format is taken from the part's content type (audio/mpeg,audio/mp3,audio/wav,audio/x-wav,audio/wave,audio/mp4,audio/m4a,audio/x-m4a,audio/webm), or from the file extension when the content type is not one of these. -
The API accepts files up to 100 MB, but the hosting
front end rejects request bodies over 32 MiB with
413before they reach the API. The effective limit for this endpoint is therefore 32 MiB per request. -
There is no upload-by-reference mode for audio. For longer
recordings, compress them (for example mono
mp3orm4a) or split them into parts under 32 MiB.
Form fields
| Field | Type | Description |
|---|---|---|
| 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 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
{
"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.
{
"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.
{
"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 }
}
}
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.
{
"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..."
}
}
Confidence voice signal is derived as 100 − mean(uncertainty,
hesitation).
Common errors
| Status | code | When |
|---|---|---|
| 400 | missing_required_field | No file field was sent or it was empty. |
| 400 | file_too_large | File 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). |
| 400 | unsupported_format | Content type or extension is not in the accepted set. |
| 400 | upload_error | The request is not multipart/form-data, or the multipart stream could not be read. |
| 400 | dissonance_requires_tone | dissonance=true was sent without tone_analysis=true. |
| 403 | insufficient_permissions | The key lacks the analyze permission. |
| 503 | storage_not_configured | Audio storage is not configured for this environment. Contact support. |
| 503 | (storage code) | Cloud Storage rejected the upload. Retry with backoff. |
| 500 | storage_error | The file could not be persisted to storage. |
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
| Parameter | Type | Description |
|---|---|---|
| idrequired | string | The job ID returned by an analyze call (for example job_xxxxxxxxxxxxxx). |
Response — queued / processing 200
{
"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.
{
"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
{
"id": "job_xxxxxxxxxxxxxx",
"status": "failed",
"created": 1774746000000,
"completed": 1774746012000,
"error": "Inference worker timed out"
}
200 even when
status is failed. Inspect the
status field, not the HTTP code, to detect
job failures.
Common errors
| Status | code | When |
|---|---|---|
| 404 | job_not_found | The job does not exist, has expired, or belongs to a different organization. |
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.
-
By analysis ID — supply
analysis_aandanalysis_b, each theidof a completed analysis in your organization (an_xxxxxxxxxxxxxx, theresult.id— not thejob_ID). -
Inline profile — supply
profile_aandprofile_b, each an object containing at minimum amotivesobject. Optional fields:cognition,affect,regulation,systems. A completed analysis result can be passed as-is.
Request body
| Field | Type | Description |
|---|---|---|
| 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 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
{
"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
| Status | code | When |
|---|---|---|
| 400 | missing_required_field | Neither (profile_a + profile_b) nor (analysis_a + analysis_b) was provided, or only one analysis ID was. |
| 400 | conflicting_fields | Both inline profiles and analysis IDs were provided in the same request. |
| 400 | invalid_field_value | An inline profile is not an object or has no motives object. |
| 400 | invalid_field_type | context is not a string. |
| 403 | insufficient_permissions | API key lacks the match permission. |
| 404 | analysis_not_found | A referenced analysis does not exist in your organization. |
| 500 | db_error | The match could not be stored. |
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
| Field | Type | Description |
|---|---|---|
| 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 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
{
"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].
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
| Status | code | When |
|---|---|---|
| 400 | missing_required_field | messages is missing, not an array, or empty. |
| 400 | invalid_field_value | An item in messages has empty or non-string content, or the array contains no user message. |
| 400 | invalid_enum_value | An item in messages has a role other than user or assistant. |
| 400 | unknown_model | model is not a recognized model or provider. |
| 400 | provider_not_configured | The selected provider is not available. |
| 403 | insufficient_permissions | API key lacks the chat permission. |
| 404 | analysis_not_found | analysis_id does not exist in your organization. |
| 500 | llm_error | The language model provider returned an error. |
List people #
Return a paginated list of people in your organization with optional tag filtering and name search.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| limitoptional | integer | Results per page. Default 20; values above 100 are capped at 100. |
| offsetoptional | integer | Pagination offset. Default 0. |
| tagoptional | string | Filter by an exact tag. |
| searchoptional | string | Case-insensitive name match. |
Response 200
{
"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
| Status | code | When |
|---|---|---|
| 400 | invalid_field_value | limit is not a positive integer, or offset is negative or not an integer. |
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
| Field | Type | Description |
|---|---|---|
| nameoptional | string | Full name. |
| roleoptional | string | Job title or role. |
| organizationoptional | string | The person's organization name. |
| tagsoptional | array of string | Free-form labels used for filtering in GET /v2/people. |
| metadataoptional | object | Arbitrary key-value data attached to this record. |
Example request
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
{
"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
| Status | code | When |
|---|---|---|
| 400 | invalid_field_type | name is not a string, tags is not an array, or metadata is not an object. |
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
| Parameter | Type | Description |
|---|---|---|
| idrequired | string | Person ID (for example pe_xxxxxxxxxxxxxx). |
Response 200
Same shape as Create a person, with analysis_count reflecting all analyses currently attached.
Common errors
| Status | code | When |
|---|---|---|
| 404 | person_not_found | No person with that ID exists in the calling organization. |
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
| Field | Type | Description |
|---|---|---|
| nameoptional | string or null | Replace the person's name. Pass null to clear. |
| roleoptional | string or null | Replace the person's role. |
| organizationoptional | string or null | Replace the organization name. |
| tagsoptional | array of string or null | Replace the tag list (full overwrite, not merge). |
| metadataoptional | object | Replace 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
| Status | code | When |
|---|---|---|
| 400 | invalid_field_type | name is not a string or null, tags is not an array or null, or metadata is not an object. |
| 404 | person_not_found | No person with that ID exists in the calling organization. |
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.
Response
204 No Content with an empty body.
Common errors
| Status | code | When |
|---|---|---|
| 404 | person_not_found | No person with that ID exists in the calling organization. |
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 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
| Status | code | When |
|---|---|---|
| 403 | insufficient_permissions | API key lacks the analyze permission. |
| 404 | person_not_found | No person with that ID exists in the calling organization. |
| 400 | missing_required_field | content is missing or not a string. |
| 400 | invalid_enum_value | mode is not "sync" or "async". |
| 500 | inference_error | Sync mode only: the worker failed during analysis. |
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
| Parameter | Type | Description |
|---|---|---|
| idrequired | string | Person ID. |
Response 200
{
"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
| Status | code | When |
|---|---|---|
| 404 | person_not_found | No person with that ID exists in the calling organization. |
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.
| Field | Type | Description |
|---|---|---|
| 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 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
{
"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 -X PUT "<upload_url>" --upload-file /path/to/interview.mp4
Common errors
| Status | code | When |
|---|---|---|
| 503 | storage_not_configured | Upload storage is not configured for this environment. Contact support. |
| 503 | upload_session_error | An upload session could not be created. Retry with backoff. |
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.
safe_use_notice
restating this.
Input modes
There are two ways to provide the video:
-
Reference mode (recommended) — send JSON
with an
upload_reffrom Create interview upload (or agcs_uriunder your organization's upload prefix). Works for videos up to 2 GB. -
Multipart mode — send
multipart/form-datawith the video in afilefield. Convenient for short clips only: the hosting front end rejects request bodies over 32 MiB with413, so anything larger must use reference mode.
Request body — reference mode (JSON)
| Field | Type | Description |
|---|---|---|
| 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 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
{
"id": "job_xxxxxxxxxxxxxx",
"object": "job",
"status": "received",
"poll_url": "/v2/interviews/job_xxxxxxxxxxxxxx",
"estimated_seconds": 460
}
Common errors
| Status | code | When |
|---|---|---|
| 400 | missing_required_field | Neither upload_ref nor gcs_uri was provided (JSON mode), or no file field was sent (multipart mode). |
| 404 | upload_not_found | The 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. |
| 400 | upload_not_found | No object exists at the referenced storage location — the PUT to the upload URL never completed. |
| 403 | gcs_uri_forbidden | gcs_uri points outside your organization's upload prefix. |
| 400 | file_too_large | The video exceeds the 2 GB limit (reference mode) or the multipart cap (use reference mode instead). |
| 400 | unsupported_format | The file is not one of the accepted video formats. |
| 503 | storage_not_configured | Upload storage is not configured for this environment. Contact support. |
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
| Parameter | Type | Description |
|---|---|---|
| idrequired | string | The job ID from the 202 response. |
Response — queued / processing 200
{
"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:
| Composite | What it flags |
|---|---|
| ai_assisted | Signs the answers were generated and read aloud — over-structured, low-spontaneity language combined with vocal strain consistent with reading. |
| speaker_continuity | Vocal-change detector — a possible mid-interview speaker swap. Low confidence; treat as a prompt to check the recording. |
| authenticity | Rehearsed or coached response patterns — inconsistent detail structure and high text-vs-tone dissonance. |
| high_concern | Combined 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.
{
"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
| Field | Description |
|---|---|
| interview | The four integrity composites, num_answers (how many candidate answers were scored), the interview-level review_recommendation, and the safe_use_notice. |
| speaker_separation | How 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, …). |
| segments | One 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_english | The detected spoken language, and whether answers were translated to English before behavioral analysis. |
| transcript | The full interview transcript with duration and the candidate's speaker label. |
| warnings | Non-fatal notices, e.g. "translated_to_english_from_de", "tone_analysis_unavailable_dissonance_limited", or "insufficient_candidate_speech". |
status_detail: "insufficient_candidate_speech",
zero-scored composites with
review_recommendation: "no_candidate_speech",
and the transcript for manual inspection.
Response — failed 200
{
"id": "job_xxxxxxxxxxxxxx",
"status": "failed",
"created": 1774746000000,
"completed": 1774746041000,
"error": "Audio could not be extracted from the video"
}
Common errors
| Status | code | When |
|---|---|---|
| 404 | job_not_found | The interview does not exist or belongs to a different organization. |
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.
Request body
| Field | Type | Description |
|---|---|---|
| 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 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.
{
"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
| Field | Description |
|---|---|
| events | What 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). |
| state | How 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. |
| preferences | Communication 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. |
| changes | Shifts 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. |
| guidance | The 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. |
| quality | status: 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. |
| policy | Support 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, timing | Operator fields for logging and support. Never show them to the participant. |
| text, debug | Only with include_text / include_debug. |
Retries and concurrency
- Resending the participant's most recent
turn_idreturns the original result (quality.inference: "replayed", warningduplicate_turn) and never counts twice. - Resending an older
turn_idreturns409 turn_already_processed; state is unchanged. - Turns of one participant are processed one at a time. If another request holds the participant too long, the call returns
409 participant_busywithRetry-After: 1.
Common errors
| Status | code | When |
|---|---|---|
| 400 | invalid_request | A field is missing or invalid, or recipe_id is unknown. param names the field. |
| 403 | insufficient_permissions | API key lacks the analyze permission. |
| 409 | turn_already_processed | The turn_id belongs to an earlier turn of this participant. |
| 409 | participant_busy | Another request for this participant is still running. Retry after Retry-After. |
| 500 | behavioral_context_failed | Unexpected 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.
{
"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 ..."
}
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.
Request body
| Field | Type | Description |
|---|---|---|
| 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
| Score | band | recommended_action |
|---|---|---|
| below 35 | low | continue |
| 35 to below 55 | elevated | adapt |
| 55 to below 75 | high | de_escalate |
| 75 and above | critical | handoff_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 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.
{
"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
| Field | Description |
|---|---|
| escalation_risk | score (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_reasons | What the agent should do now (continue | adapt | de_escalate | handoff_to_human) and why. |
| flags | Triggers 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. |
| components | The 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). |
| evidence | The matched escalation markers (lexical), the Thorsten-4 signals used (thorsten; null when unavailable), and how much customer text was analyzed. |
| human_understanding | Operator-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_playbook | For the next reply: now, say, avoid, and an operator status_line (not for the customer). |
| handoff_packet | Present 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. |
| trajectory | One { turn, score, band, action } per turn so far. |
| guidance | Only with include_guidance: true. |
Common errors
| Status | code | When |
|---|---|---|
| 400 | invalid_request | customer_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. |
| 403 | insufficient_permissions | API key lacks the analyze permission. |
| 500 | escalation_failed | Unexpected 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.
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.
{
"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
| Status | code | When |
|---|---|---|
| 400 | invalid_request | session_id has invalid characters or length. |
| 403 | insufficient_permissions | API key lacks the analyze permission. |
| 404 | session_not_found | GET only: no session with that ID in your organization (sessions expire 24 hours after the last turn). |
| 500 | escalation_session_failed | Unexpected server error. Quote the request_id. |
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
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):
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.
401 with invalid_oauth_token,
missing_org_claim or
organization_not_provisioned.
Browser origins and rate limits
-
Requests that carry an
Originheader (browser apps) must come from an allow-listed origin, otherwise they get403 origin_not_allowed. Server-to-server clients send noOriginand are unaffected. This check is currently in monitoring mode: nothing is rejected yet. -
Only
tools/callmessages count toward your rate limits;initialize,tools/listand notifications are free.
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
| Tool | Required input | What it does |
|---|---|---|
| read_room | conversation_id, participant_id, turn_id, message | Behavioral 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_risk | customer_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_session | session_id | Supervisor 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
| Tool | Required input | What it does |
|---|---|---|
| analyze_text | content | Generic 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_candidate | content | Hiring 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_fit | person_a_content, person_b_content | Team fit between two people from a writing sample each: interaction pattern, complementary strengths, likely friction, and one recommendation. Optional labels and team_context. |
| analyze_spokesperson | content | Spokesperson, 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_message | content | Reads 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_strategy | buyer_content | Turns 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_fit | seller_content, buyer_content | The 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_people | person_a_content, person_b_content, environment | Two-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):
claude mcp add --transport http millionways https://api.millionways.ai/mcp \ --header "Authorization: Bearer mw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Claude Code project file
(.mcp.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):
{
"mcpServers": {
"millionways": {
"url": "https://api.millionways.ai/mcp",
"headers": {
"Authorization": "Bearer mw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
}
-
IBM watsonx Orchestrate and other agent
platforms: add a remote MCP server with the URL
https://api.millionways.ai/mcp(Streamable HTTP) and API-key authentication, and paste the key as-is. The server accepts it whether the platform sends it asAuthorization(with or withoutBearer) or in anx-api-key,api-keyorapi_keyheader. -
Claude Desktop and claude.ai: add a custom
connector with the URL
https://api.millionways.ai/mcp. Custom connectors sign in with OAuth rather than a pasted key, so your organization must be enabled by millionways first (see OAuth needs an enabled organization above).
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.
Top-level object
| Field | Type | Stability | Description |
|---|---|---|---|
| id | string | stable | Unique analysis ID, prefixed an_. |
| object | string | stable | Always "analysis". |
| created | integer | stable | Unix timestamp (seconds) when the analysis was produced. |
| model | string | stable | Model identifier, for example "thorsten-4". |
| motives | object | stable | Motive scores, dominant motive, prediction class, and confidence map. |
| cognition | object | stable | Cognitive style dimensions. |
| affect | object | stable | Affect, valence, and behavioral level distribution. |
| regulation | object | stable | Self-regulation capacities. Present when options.include_psi is true (the default). |
| systems | object | stable | PSI macrosystem activations, dominant system, and style mapping. Present when options.include_psi is true (the default). |
| insights | object | stable | Summary, strengths, and development areas. Present when options.include_insights is true (the default). |
| usage | object | stable | Usage metrics: character count and model, plus audio_seconds for audio. |
| transcript, analyses, tone_analysis, dissonance | object / array | stable | Audio results only. See Analyze audio. |
| descriptions | object | stable | Narrative descriptions for motives, affect, cognition, and behavioral levels. Only in the synchronous POST /v2/analyze response; not in polled job results. |
Detailed field map
| Field | Type | Constraints | Description |
|---|---|---|---|
| motives | |||
| motives.power | number | 0–100 | Power motive strength. |
| motives.achievement | number | 0–100 | Achievement motive strength. |
| motives.contact | number | 0–100 | Contact motive strength. |
| motives.dominant | string | enum | One of "power", "achievement", "contact". |
| motives.prediction | string | — | Top-1 prediction class label from the underlying classifier. |
| motives.confidence_scores | object | — | 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.detail | number | 0–100 | Detail orientation score. |
| cognition.realization | number | 0–100 | Realization orientation score (complement of detail). |
| cognition.analytical | number | 0–100 | Analytical orientation score. |
| cognition.holistic | number | 0–100 | Holistic orientation score. |
| cognition.internal | number | 0–100 | Internal orientation score. |
| cognition.external | number | 0–100 | External orientation score. |
| cognition.goal | number | 0–100 | Goal orientation score. |
| cognition.path | number | 0–100 | Path orientation score. |
| affect | |||
| affect.approach | number | 0–100 | Approach orientation score. |
| affect.avoidance | number | 0–100 | Avoidance orientation score. |
| affect.positive | number | 0–100 | Positive affect score. |
| affect.negative | number | 0–100 | Negative affect score. |
| affect.level | number | 1.0–5.0 | Behavioral level (continuous). |
| affect.level_distribution | object | — | Distribution over level1 through level5; values sum to 100. |
| regulation | |||
| regulation.self_motivation | number | 0–100 | Capacity for self-generated motivation. |
| regulation.self_relaxation | number | 0–100 | Capacity for self-driven downregulation. |
| regulation.action_orientation_failure | number | 0–100 | Action orientation after failure events. |
| regulation.action_orientation_decision | number | 0–100 | Action orientation when initiating a decision. |
| regulation.volitional_efficiency | number | 0–100 | Volitional efficiency score. |
| regulation.stress_resilience | number | 0–100 | Stress resilience score. |
| systems (PSI macrosystems) | |||
| systems.extension_memory | number | 0–100 | Extension memory activation. |
| systems.object_recognition | number | 0–100 | Object recognition activation. |
| systems.intention_memory | number | 0–100 | Intention memory activation. |
| systems.intuitive_behavior | number | 0–100 | Intuitive behavior activation. |
| systems.dominant | string | enum | Dominant system key. |
| systems.personality_style | string | enum | Mapped style: agreeable, self_determined, conscientious, independent. |
| systems.style_scores | object | — | Per-style scores keyed by the same enum values. |
| insights / usage | |||
| insights.summary | string | — | Narrative summary of the profile. |
| insights.strengths | array of string | — | Key strengths surfaced from the profile. |
| insights.development_areas | array of string | — | Suggested development areas. |
| usage.characters | integer | ≥ 0 | Character count of the processed input. |
| usage.model | string | — | Model used for usage accounting. |
| descriptions | object | — | 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.
| Dimension | Band | Meaning |
|---|---|---|
| Achievement Motive | Dominant | Strongly driven by mastery, excellence, and continuous improvement, with very high standards for performance. |
| Achievement Motive | Moderate | Reliably goal-oriented and growth-focused, balancing quality with pragmatism rather than perfectionism. |
| Achievement Motive | Noticeable | Cares about achievement but often prioritizes relationships, flexibility, or well-being over relentless performance. |
| Power Motive | Dominant | Strongly motivated to influence, lead, persuade, and shape outcomes through authority or impact. |
| Power Motive | Moderate | Naturally inclined to guide and inspire others, with leadership energy that is confident but more balanced. |
| Power Motive | Noticeable | Can influence and lead when needed, but tends to do so selectively and with quieter authority. |
| Contact Motive | Dominant | Deeply driven by closeness, trust, and emotionally meaningful relationships. |
| Contact Motive | Moderate | Warm, connection-oriented, and strong at rapport-building, with a preference for harmony and reciprocity. |
| Contact Motive | Noticeable | Values relationships, but is more selective and independent in where emotional energy is invested. |
| Approach / Avoidance | High Approach | Moves toward challenges with optimism, flexibility, and resilient goal pursuit. |
| Approach / Avoidance | Balanced | Combines ambition with caution, weighing opportunities and risks before acting. |
| Approach / Avoidance | High Avoidance | More likely to protect against pressure, threat, or failure through hesitation, withdrawal, or overthinking. |
| External / Internal | High External | Energized by action, people, and outside feedback, with a naturally expressive and outward-facing style. |
| External / Internal | Balanced | Blends social engagement with reflection, shifting between interaction and depth as needed. |
| External / Internal | High Internal | More self-directed, reflective, and inwardly anchored, preferring depth and authenticity over surface interaction. |
| Detail / Holistic | High Detail | Focused on precision, structure, and getting specifics right. |
| Detail / Holistic | Balanced | Able to manage both specifics and the broader strategic picture. |
| Detail / Holistic | High Holistic | Naturally thinks in systems, patterns, and long-range context rather than isolated details. |
| Intuitive / Analytical | High Intuitive | Quickly reads patterns, unspoken needs, and emerging possibilities. |
| Intuitive / Analytical | Balanced | Integrates instinct and logic, using both feel and structure in decision-making. |
| Intuitive / Analytical | High Analytical | Relies on logic, evidence, and structured evaluation to make decisions. |
| Goal / Path | High Goal | Strongly oriented toward outcomes, targets, and measurable achievement. |
| Goal / Path | Balanced | Cares about both reaching the objective and the quality of the process used to get there. |
| Goal / Path | High Path | More motivated by the journey, learning, and relationship-building process than by the end result alone. |
| Self-Motivation | High | Easily generates internal energy and enthusiasm to tackle difficult, boring, or unappealing tasks. |
| Self-Motivation | Balanced | Capable of pushing through necessary tasks but may occasionally need external deadlines or incentives. |
| Self-Motivation | Low | Struggles to find the drive for uninteresting tasks, often relying heavily on external pressure to start. |
| Self-Relaxation | High | Quickly calms down and recovers from stress, maintaining composure and focus under pressure. |
| Self-Relaxation | Balanced | Generally manages stress well but requires active strategies or dedicated time to fully decompress. |
| Self-Relaxation | Low | Finds it difficult to turn off anxiety or tension, often carrying stress and physical tension long after the event. |
| Action Orientation (Failure) | High | Rapidly bounces back from setbacks, focusing on future solutions rather than dwelling on past mistakes. |
| Action Orientation (Failure) | Balanced | Processes setbacks thoughtfully before moving on, balancing necessary reflection with forward momentum. |
| Action Orientation (Failure) | Low | Tends to ruminate on mistakes or negative feedback, making it harder to let go and move past setbacks. |
| Action Orientation (Decision) | High | Swiftly moves from planning to execution, making decisions and initiating action without unnecessary hesitation. |
| Action Orientation (Decision) | Balanced | Weighs options carefully but ultimately takes decisive action within a reasonable timeframe. |
| Action Orientation (Decision) | Low | Prone to procrastination or over-analyzing, finding it difficult to initiate the very first step of a task. |
| Volitional Efficiency | High | Highly effective at translating intentions into actions smoothly, without wasting mental energy. |
| Volitional Efficiency | Balanced | Generally productive and steady, though sustaining focus on highly complex tasks takes some deliberate effort. |
| Volitional Efficiency | Low | Frequently expends high mental effort to stay on track, leading to faster cognitive fatigue and burnout. |
| Stress Resilience | High | Remains highly stable, adaptable, and functional even in highly demanding, chaotic, or unpredictable situations. |
| Stress Resilience | Balanced | Handles moderate pressure effectively but may feel the strain and require support during prolonged crises. |
| Stress Resilience | Low | Easily overwhelmed by unexpected demands or heavy pressure, requiring a supportive environment to function best. |
| Ext. Memory (Self-Determined) | High | Deeply anchored in authentic values, naturally seeing the big picture and drawing on a wealth of personal experience. |
| Ext. Memory (Self-Determined) | Balanced | Connects well with inner values while remaining practical and adaptable to the immediate situation at hand. |
| Ext. Memory (Self-Determined) | Low | May lose touch with the broader context or personal needs when faced with sudden stress or rigid rules. |
| Obj. Recognition (Conscientious) | High | Highly alert to errors, discrepancies, and fine details, ensuring rules and high standards are strictly met. |
| Obj. Recognition (Conscientious) | Balanced | Values accuracy and quality control but avoids getting completely bogged down in rigid perfectionism. |
| Obj. Recognition (Conscientious) | Low | Tends to overlook finer details or strict rules, preferring a more relaxed, improvisational, or broad approach. |
| Intention Memory (Independent) | High | Strongly analytical and disciplined, holding firm to long-term plans and executing them methodically and logically. |
| Intention Memory (Independent) | Balanced | Maintains clear goals and logical plans while allowing some flexibility for changes in the environment. |
| Intention Memory (Independent) | Low | Prefers spontaneity over strict planning, often shifting goals based on immediate circumstances or new information. |
| Intuitive Behavior (Agreeable) | High | Acts spontaneously and smoothly, effortlessly adapting to social contexts, reading the room, and going with the flow. |
| Intuitive Behavior (Agreeable) | Balanced | Blends natural, go-with-the-flow responsiveness with occasional deliberate planning and boundary-setting. |
| Intuitive Behavior (Agreeable) | Low | Prefers 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 Levels | Level 1 | Intrinsically aligned, intuitive, energized, and operating in a natural flow state. |
| Behavioral Levels | Level 2 | Highly satisfied and creative, but more fueled by external standards, recognition, and achievement. |
| Behavioral Levels | Level 3 | Generally resilient and functional, though emotionally affected by setbacks and adapting through reflection. |
| Behavioral Levels | Level 4 | Under intense pressure, urgent, self-questioning, and striving to maintain control while solving hard problems. |
| Behavioral Levels | Level 5 | More weighed down by negative emotion, hesitation, low energy, and risk-avoidance, making initiative and creativity harder. |
| Power Motive | Level 1 | Effortlessly charismatic and inspiring, naturally drawing others to their vision while remaining unfazed by criticism. |
| Power Motive | Level 2 | Thrives on leading and motivating groups, using challenges and the pursuit of status to fuel a dynamic and persuasive energy. |
| Power Motive | Level 3 | Deeply values having a respected voice, actively shaping circumstances to guide others while using criticism as a tool for personal growth. |
| Power Motive | Level 4 | Urgently driven to influence and direct others, often employing assertive tactics but prone to impatience and strong emotional reactions to criticism. |
| Power Motive | Level 5 | Desires to make an impact but feels paralyzed by self-doubt and criticism, requiring a highly safe and supportive environment to share their voice. |
| Achievement Motive | Level 1 | Intrinsically fueled by the joy of mastering demanding goals, viewing daunting challenges as exciting opportunities rather than sources of stress. |
| Achievement Motive | Level 2 | Highly motivated by progress, excellence, and recognition, tackling challenges with enthusiasm and quickly pivoting when mistakes occur. |
| Achievement Motive | Level 3 | Finds deep satisfaction in achieving goals, maintaining a steadfast and resilient focus even when momentarily disrupted by stress or mistakes. |
| Achievement Motive | Level 4 | Relentlessly pushes for progress and solutions, often overextending themselves and experiencing irritation or self-criticism when facing obstacles. |
| Achievement Motive | Level 5 | Holds high standards but currently feels overwhelmed and energetically drained, with a fear of failure making it difficult to take decisive action. |
| Contact Motive | Level 1 | Effortlessly forms profound, authentic bonds, radiating warmth and empathy while remaining entirely unbothered by the prospect of rejection. |
| Contact Motive | Level 2 | Naturally builds deep, trusting relationships and enthusiastically welcomes new connections, recovering quickly from occasional social setbacks. |
| Contact Motive | Level 3 | Intentionally cultivates deep, enduring bonds, drawing on high empathy to support others while feeling rejection deeply before bouncing back. |
| Contact Motive | Level 4 | Craves meaningful connections but has limited social energy, fiercely protecting a tight inner circle while finding broader social demands draining. |
| Contact Motive | Level 5 | Deeply 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.
| HTTP | code | Description |
|---|---|---|
| 400 | invalid_json | The request body is not valid JSON. |
| 400 | invalid_request | The request failed validation. param names the field when known. |
| 400 | missing_required_field | A required field is absent. |
| 400 | invalid_field_type | A field has the wrong JSON type. |
| 400 | invalid_field_value | A field is the right type but outside the allowed range or set. |
| 400 | invalid_enum_value | A field's value is not one of the accepted enum values. |
| 400 | conflicting_fields | Mutually exclusive fields were both provided. |
| 400 | file_too_large | An uploaded file exceeds its size limit. |
| 400 | unsupported_format | The uploaded file format is not in the accepted set. |
| 400 | upload_error | A multipart upload could not be parsed. |
| 400 | upload_not_found | Interview reference mode: no file exists at the referenced storage location. |
| 400 | dissonance_requires_tone | dissonance=true without tone_analysis=true. |
| 400 | unknown_model | Chat: the requested model is not recognized. |
| 400 | provider_not_configured | Chat: the selected model provider is not available. |
| 401 | missing_api_key | No credential header was sent, or the token is empty. |
| 401 | invalid_api_key | The supplied key does not exist. |
| 401 | inactive_api_key | The key has been deactivated. |
| 401 | invalid_oauth_token | An OAuth access token is invalid, expired, or was not issued for this resource. |
| 401 | missing_org_claim | An OAuth access token carries no organization. |
| 401 | organization_not_provisioned | The OAuth user's organization has not been enabled by millionways. |
| 403 | insufficient_permissions | The key lacks a permission required by the endpoint. |
| 403 | insufficient_scope | The key lacks the scope required by the endpoint. |
| 403 | gcs_uri_forbidden | A storage URI points outside your organization's upload prefix. |
| 403 | origin_not_allowed | /mcp: the browser Origin is not allow-listed (monitoring only for now). |
| 404 | route_not_found | Authenticated request to a route that does not exist. |
| 404 | job_not_found | The job ID does not exist, has expired, or belongs to a different organization. |
| 404 | upload_not_found | An interview upload_ref does not exist, is older than 24 hours, or belongs to another organization. |
| 404 | person_not_found | The person ID does not exist or belongs to a different organization. |
| 404 | analysis_not_found | A referenced analysis does not exist in your organization. |
| 404 | session_not_found | No escalation session with that ID (sessions expire 24 hours after the last turn). |
| 404 | not_found | Any other resource that does not exist. |
| 405 | method_not_allowed | The method is not supported (for example GET /mcp). |
| 409 | turn_already_processed | Read the room: the turn_id belongs to an earlier turn. |
| 409 | participant_busy | Read the room: another request for the participant is running. Retry after Retry-After. |
| 413 | payload_too_large | The request body is too large. |
| 415 | unsupported_media_type | The Content-Type is not accepted. |
| 429 | rate_limit_exceeded | The key's per-minute ceiling was exceeded (when enforcement is on). |
| 429 | daily_quota_exceeded | The key's daily quota was exceeded (when enforcement is on). |
| 500 | internal_error | Unhandled server error. |
| 500 | inference_error | The inference worker failed to produce a result. |
| 500 | llm_error | An LLM-backed endpoint returned an error. |
| 500 | invalid_model_output | An LLM-backed endpoint returned malformed output. |
| 500 | storage_error | A storage operation failed (503 when the uploaded interview object could not be read). |
| 500 | db_error | A result could not be stored. |
| 500 | behavioral_context_failed | Read the room failed unexpectedly. |
| 500 | escalation_failed | Escalation risk failed unexpectedly. |
| 500 | escalation_session_failed | An escalation session could not be read or reset. |
| 503 | service_unavailable | The service is temporarily unavailable. |
| 503 | storage_not_configured | Upload storage is not configured for this environment. |
| 503 | upload_session_error | A 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
evaluate_candidateis enabled per organization, andGET /v2/mcp/toolsreturns the MCP tools a key can use. OAuth access tokens are for/mcponly; the REST API takes API keys. Both changes are in monitoring mode before they are enforced. The MCP server reports version0.7.0.- Documented the live-conversation endpoints: Read the room (
POST /v2/behavioral-context, publicGET /v2/behavioral-context/skill) and Escalation risk (POST /v2/escalation-risk,GET/DELETE /v2/escalation-risk/sessions/:session_id, publicGET /v2/escalation-risk/skill). - The MCP server catalog now lists all eleven tools, including
read_room,assess_escalation_riskandget_escalation_session./mcpis stateless andPOST-only (GET/DELETEreturn405), supports protocol versions up to2025-11-25, and publishes tool annotations. OAuth 2.1 sign-in is documented, browserOriginvalidation is in monitoring mode, and connection examples no longer rely on a locally installed package. - Every error, including malformed JSON, oversized bodies, unsupported Content-Types, unknown routes and unhandled server errors, now uses the
{"error": {"type", "code", "message"}}envelope.5xxerrors carry no internal details and include arequest_id; every response has anx-request-idheader. New error types:not_found_error(replacesnot_found),conflict_error,rate_limit_error. - Rate limiting is now per API key: a per-minute ceiling plus the key's daily quota. It is currently in monitoring mode, so no request is rejected; when enforced, an over-limit request gets
429withRetry-After. - Corrected the documentation to match the API: job IDs start with
job_; job-envelope timestamps are milliseconds; job results are kept for one hour;/v2/analyze/audioaccepts at most 32 MiB per request in practice;mw_test_keys behave exactly likemw_live_keys; the permission each endpoint checks;/v2/chatdefaults and response fields; interviewupload_refvalidity (24 hours). - Added Interview Integrity Analysis:
POST /v2/interviews/uploads(direct-to-storage upload URLs for videos up to 2 GB),POST /v2/interviews/analyze, andGET /v2/interviews/:id. Submit a recorded interview video and receive four calibrated integrity composites (ai_assisted,speaker_continuity,authenticity,high_concern) with per-answer behavioral, voice tone, and dissonance detail. - Documented the hosted MCP server at
/mcp: transport, authentication (API key and OAuth), and the full tool catalog including the newsales_outreach_strategyandseller_buyer_fittools. - The documentation now supports light and dark themes — use the toggle in the sidebar; the default follows your system preference.
- Added the
tone_analysisoption toPOST /v2/analyze/audio(voice tone analysis) and documented its result object. Audio transcription now runs on an upgraded speech-to-text pipeline with automatic fallback. - Documentation restructured into Get started, Concepts, Endpoints, and Reference sections.
- Documented
POST /v2/analyze/audio,POST /v2/people/:id/analyze, andGET /v2/people/:id/trajectory. - Corrected
POST /v2/chatrequest shape to use themessagesarray (previously documented as a singlemessagefield). - Added explicit retry guidance, polling cadence, pagination conventions, and versioning policy.