87 lines
4.1 KiB
YAML
87 lines
4.1 KiB
YAML
|
openapi: 3.1.0
|
||
|
|
info:
|
||
|
|
title: Subject home overview
|
||
|
|
version: 0.99.24
|
||
|
|
paths:
|
||
|
|
/api/v1/subjects/{id}/home-overview:
|
||
|
|
get:
|
||
|
|
operationId: subjectHomeOverview
|
||
|
|
summary: Current calendar week and latest finished conversation
|
||
|
|
description: >-
|
||
|
|
Read-only, subject-scoped metadata independent of conversation-list pagination or filters.
|
||
|
|
Week boundaries use the subject timezone, Monday inclusive to next Monday exclusive.
|
||
|
|
Entire duration belongs to the session start date, including midnight/week crossings.
|
||
|
|
Legacy sessions require started_at and ended_at; DIRECT sessions require ended_at and
|
||
|
|
a valid finalized USER or ASSISTANT utterance. Interrupted sessions with this evidence count;
|
||
|
|
preparation failures, active sessions, future end times, and deleted sources do not count.
|
||
|
|
DIRECT duration is created_at to ended_at, because no reliable connected_at is stored.
|
||
|
|
Latest conversation is independent of the week and never replaced with an older recap.
|
||
|
|
Metadata requires household conversation-read access; recap additionally requires the
|
||
|
|
independent memory grant, current storage consent, and applicable privacy fencing.
|
||
|
|
Legacy unclassified summaries require sensitive access. DIRECT recap is an existing
|
||
|
|
active normal memory from that exact session, not a newly synthesized full summary.
|
||
|
|
security:
|
||
|
|
- bearerAuth: []
|
||
|
|
parameters:
|
||
|
|
- name: id
|
||
|
|
in: path
|
||
|
|
required: true
|
||
|
|
schema: {type: string, format: uuid}
|
||
|
|
responses:
|
||
|
|
'200':
|
||
|
|
description: Home overview; no-store
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
data: {$ref: '#/components/schemas/HomeOverview'}
|
||
|
|
'400': {description: Invalid subject ID or unsupported query parameters}
|
||
|
|
'401': {description: Authentication required}
|
||
|
|
'403': {description: Subject metadata access denied}
|
||
|
|
components:
|
||
|
|
securitySchemes:
|
||
|
|
bearerAuth: {type: http, scheme: bearer}
|
||
|
|
schemas:
|
||
|
|
HomeOverview:
|
||
|
|
type: object
|
||
|
|
required: [subject_id, timezone, week_start, week_end, conversation_count, total_duration_ms, daily, latest_conversation]
|
||
|
|
properties:
|
||
|
|
subject_id: {type: string, format: uuid}
|
||
|
|
timezone: {type: string, example: Asia/Shanghai}
|
||
|
|
week_start: {type: string, format: date}
|
||
|
|
week_end: {type: string, format: date, description: Exclusive next Monday}
|
||
|
|
conversation_count: {type: integer, minimum: 0}
|
||
|
|
total_duration_ms: {type: integer, format: int64, minimum: 0}
|
||
|
|
daily:
|
||
|
|
type: array
|
||
|
|
minItems: 7
|
||
|
|
maxItems: 7
|
||
|
|
items:
|
||
|
|
type: object
|
||
|
|
required: [date, conversation_count, duration_ms]
|
||
|
|
properties:
|
||
|
|
date: {type: string, format: date}
|
||
|
|
conversation_count: {type: integer, minimum: 0}
|
||
|
|
duration_ms: {type: integer, format: int64, minimum: 0}
|
||
|
|
latest_conversation:
|
||
|
|
oneOf:
|
||
|
|
- type: 'null'
|
||
|
|
- $ref: '#/components/schemas/HomeConversation'
|
||
|
|
HomeConversation:
|
||
|
|
type: object
|
||
|
|
required: [id, source, status, started_at, ended_at, duration_ms, summary_state]
|
||
|
|
properties:
|
||
|
|
id: {type: string, format: uuid}
|
||
|
|
source: {type: string, enum: [conversation, call_memory]}
|
||
|
|
status: {type: string, description: Original terminal status, including FAILED for an interrupted actual conversation}
|
||
|
|
started_at: {type: string, format: date-time}
|
||
|
|
ended_at: {type: string, format: date-time}
|
||
|
|
duration_ms: {type: integer, format: int64, minimum: 0}
|
||
|
|
summary: {type: string, description: Only present when authorized and READY}
|
||
|
|
summary_kind: {type: string, enum: [conversation_summary, memory]}
|
||
|
|
summary_state:
|
||
|
|
type: string
|
||
|
|
enum: [READY, PROCESSING, INSUFFICIENT_TRANSCRIPT, NO_SUMMARY, SYNC_FAILED, UNAVAILABLE]
|
||
|
|
description: UNAVAILABLE covers access, storage consent, or privacy restrictions without revealing hidden content.
|