Response Schema

This page documents request validation, output modes, and response envelope shapes for POST /v1.0.0/analyze.

Per-speaker analysis

POST /v1.0.0/analyze/speakers accepts the same bearer authentication and input_text field. It returns full positive and negative analysis for each explicit speaker, rather than a transcript-wide assessment. The existing /analyze endpoint and its nine output modes remain unchanged. The speaker endpoint currently supports full output only; there is no mode parameter.

{
  "input_text": "Speaker 1: I keep revisiting the meeting.\nSpeaker 2: I will ask for feedback tomorrow.\nSpeaker 1: I am still thinking about it."
}

Transcript rules:

Every nonblank line must be Speaker label: utterance. Labels start with a letter, have at most 80 characters, and may contain letters, numbers, spaces, underscores, apostrophes, dots, and hyphens.
Use one turn per line. Repeat the label on wrapped text; remove timestamps and transcript headings before submission. Unlabelled lines are rejected.
Matching ignores label case and repeated spaces. The first spelling is kept for display. Different names or aliases remain different speakers.
Between 1 and 8 speakers; at most 50,000 characters across the entire input.
Speaker IDs follow first appearance. Turn IDs count nonblank lines, starting at 1, and refer back to the submitted transcript.

Each speaker gets the same marker table and explanation shapes as Full Output. The following illustrates the envelope with empty tables; it is not a model evaluation or the expected analysis of the example above:

{
  "analysis_scope": "per_speaker",
  "speaker_count": 2,
  "speakers": [
    {
      "speaker_id": "speaker_1",
      "speaker_label": "Speaker 1",
      "turn_ids": [1, 3],
      "negative_markers": {"table_output": [], "explanatory_output": "..."},
      "positive_markers": {"table_output": [], "explanatory_output": "..."}
    },
    {
      "speaker_id": "speaker_2",
      "speaker_label": "Speaker 2",
      "turn_ids": [2],
      "negative_markers": {"table_output": [], "explanatory_output": "..."},
      "positive_markers": {"table_output": [], "explanatory_output": "..."}
    }
  ]
}

Both category calls receive the complete ordered transcript and explicit speaker IDs. The model selects source excerpt IDs restricted to the attributed speaker. Python inserts the exact original quotation and turn ID into the existing result shape. Other turns supply context; evidence must quote an existing turn owned by the attributed speaker. Each category must return exactly one entry per supplied speaker, including empty findings. Unknown, duplicate or missing speakers, foreign turn references and quotations absent from the referenced turn fail validation. Questions, advice and reported beliefs are excluded unless the speaker independently endorses them. Mechanical checks cannot establish the psychological correctness of attribution; representative examples need review. IDs are request-local labels, not verified identities or audio diarization.

Full output uses two concurrent calls total for one to eight speakers. Both categories must succeed; no partial assessment is returned as a success. One transient retry per category permits at most four provider attempts; invalid schemas, refusals, truncation and attribution errors never trigger repair calls. Sibling work is cancelled on failure or request-task cancellation.

One transcript consumes one request under the existing quota policy. Input, transcript, mode and estimated-token validation occur before quota consumption. Once quota enforcement has run, provider failures consume the request; retries do not consume additional requests. Existing user/IP quota accounting and Redis failure behavior are unchanged. Successful requests write one usage record; its input/output token counts remain estimates, separate from provider-reported usage in content-free telemetry.

The website's Text / Transcript selector uses the respective endpoint and renders separate expandable speaker results. See analysis budgets.

Request schema

{
  "input_text": "string"
}

Validation:

input_text cannot be empty after trim
max length: 50,000 Unicode code points, including whitespace and speaker labels
per-category prompt, serialized input, schema and message overhead must fit the configured estimated-token budget; input is never silently truncated

Common success headers

All successful analyze responses include:

X-Requests-Remaining: remaining monthly requests for current user tier
X-Reset-At: ISO-8601 timestamp when current window resets
X-Request-ID: correlation ID for content-free analysis telemetry

Output mode payloads

`Full Output`

{
  "negative_markers": {
    "table_output": [
      {
        "Psychological_Marker": "Rumination",
        "Sub_Type": "Self-Critical Loop",
        "Confidence": 8,
        "Valence": -2,
        "Arousal": 7,
        "Prevalence": 5
      }
    ],
    "explanatory_output": "..."
  },
  "positive_markers": {
    "table_output": [
      {
        "Skill": "Affect Regulation",
        "Sub_Dimension": "Pause before reaction",
        "Competence": 7,
        "Confidence": 8,
        "Skill_Use": "Applied",
        "Reflection_Depth": "Moderate"
      }
    ],
    "explanatory_output": "..."
  }
}

`Negative Table`

{
  "negative_markers": {
    "table_output": [
      {
        "Psychological_Marker": "Cognitive Distortion",
        "Sub_Type": "Catastrophizing",
        "Confidence": 8,
        "Valence": -2,
        "Arousal": 7,
        "Prevalence": 4
      }
    ]
  }
}

`Negative Explanatory`

{
  "negative_markers": {
    "explanatory_output": "..."
  }
}

`Negative Combined`

{
  "negative_markers": {
    "table_output": [],
    "explanatory_output": "..."
  }
}

`Positive Table`

{
  "positive_markers": {
    "table_output": [
      {
        "Skill": "Self Efficacy",
        "Sub_Dimension": "Agency statement",
        "Competence": 7,
        "Confidence": 8,
        "Skill_Use": "Applied",
        "Reflection_Depth": "Moderate"
      }
    ]
  }
}

`Positive Explanatory`

{
  "positive_markers": {
    "explanatory_output": "..."
  }
}

`Positive Combined`

{
  "positive_markers": {
    "table_output": [],
    "explanatory_output": "..."
  }
}

`Both Tables Combined`

{
  "combined_tables": {
    "negative_table_output": [],
    "positive_table_output": []
  }
}

`Both Explanatory Combined`

{
  "combined_explanatory": {
    "negative_explanatory_output": "...",
    "positive_explanatory_output": "..."
  }
}

Failures

Input/transcript/token-budget errors return 400 (invalid request-body types return 422); authentication and quota behavior remain unchanged. Invalid or incomplete model output returns 502. Exhausted transient provider failures return 503; exhausted attempt timeouts or the pipeline deadline return 504. Error details are sanitized and do not contain provider response bodies or submitted content.

{
  "detail": {
    "error": "invalid_model_output",
    "message": "AI response failed validation; please try again"
  }
}

Empty findings are a successful result with an empty table and the readable message: "Insufficient evidence to identify markers at the required confidence threshold." Table and explanation projections use the same validated findings.