InterpretSession

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/motaword/json-schema/motaword-interpret-session-schema.json",
  "title": "InterpretSession",
  "description": "State record for a scheduled video interpretation session. One per project.",
  "x-generated": "2026-10-28",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/motaword-api-openapi.yml#/components/schemas/InterpretSession",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    },
    "project_id": {
      "type": "integer",
      "format": "int64"
    },
    "room_name": {
      "type": "string",
      "description": "Deterministic LiveKit room name (e.g. `interpret-project-74`)."
    },
    "status": {
      "type": "string",
      "enum": [
        "scheduled",
        "ringing",
        "live",
        "ended",
        "canceled"
      ]
    },
    "mode": {
      "type": "string",
      "description": "Who serves the session — `human` (a human interpreter joins) or `ai`\n(the AI interpreter worker joins instead). Defaults to `human`.\n",
      "enum": [
        "human",
        "ai"
      ]
    },
    "scheduled_start_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "scheduled_duration_minutes": {
      "type": [
        "integer",
        "null"
      ]
    },
    "started_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "ended_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "recording_enabled": {
      "type": "boolean"
    },
    "recording_url": {
      "type": [
        "string",
        "null"
      ]
    },
    "guest_token": {
      "type": [
        "string",
        "null"
      ],
      "description": "Opaque token used by the public guest-join link. Customers share it via a URL; it rotates via the rotate-guest-token endpoint."
    },
    "context_note": {
      "type": [
        "string",
        "null"
      ],
      "description": "Customer-supplied 1-2 sentence brief shown to the interpreter before the room."
    },
    "domain": {
      "type": [
        "string",
        "null"
      ],
      "description": "Domain tag like \"medical\" / \"legal\" / \"business\" / \"general\". Advisory only."
    },
    "usage": {
      "type": "object",
      "description": "Derived operational-time figures for this session, computed from the\npresence timeline (`interpret_session_event`). Refreshes on every\nsession poll. Source of truth for the in-call \"Remaining HH:MM\"\ndisplay and for billing reconciliation. The frontend ticks\n`billable_seconds_used` locally between polls only when both\n`interpreter_present` and `customer_present` are true.\n",
      "properties": {
        "interpreter_present": {
          "type": "boolean",
          "description": "True iff at least one participant with role=vendor is currently in the LiveKit room."
        },
        "customer_present": {
          "type": "boolean",
          "description": "True iff at least one participant with role=customer is currently in the LiveKit room."
        },
        "billable_seconds_used": {
          "type": "integer",
          "description": "Total accumulated seconds during which both an interpreter and a\ncustomer were simultaneously present. Guests do not gate billing.\nAuthoritative — clients should display this verbatim and only\ntick locally between polls when both `*_present` flags are true.\n"
        },
        "billable_started_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "UTC ISO8601 timestamp marking the start of the currently open\nbillable interval (i.e. when the room most recently transitioned\nto \"interpreter + customer both present\"). Null when no billable\ninterval is currently open.\n"
        },
        "last_event_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "ISO8601 timestamp of the most recent presence event seen for this session. Useful as a cache-staleness hint."
        }
      }
    }
  }
}