Session store

Sellable product

This capability is granted by an API key scoped to the `` product (product face). See the product reference below.

Cross-modal conversation/session + transcript + recording-ref store as a shared capability. Consumers: voice (call history/transcript) + aakhara/anjaan (chat/roleplay session history) = >=2. INTERNAL (no product-face). Recording BYTES live in media-transcode/cdn; this cap stores the transcript + recording REFS only. Fail-closed: writes/reads return 503 when the store is unavailable.

• Group: Voice & AI
• Contract: contracts/session-store/v1/openapi.yaml
• Public base: https://api.vagarylabs.com (the consolidated API gateway — one host, per-brand sibling api.<zone>)
• Auth: a product API key (vgk_…) issued from the console — Authorization: Bearer vgk_…
• Product face (customer-keyed):
  • https://api.vagarylabs.com/product/v1/session-store/sessions

Endpoints

Method	Path	Summary
POST	/v1/sessions	Create a conversation/session (any modality)
GET	/v1/sessions	List a tenant's sessions (keyset-paginated, most-recent first)
GET	/v1/sessions/{session_id}	Full session + ordered transcript + recording refs
DELETE	/v1/sessions/{session_id}	GDPR (Art.17) erasure — forget the session + transcript + recording REFS (IDOR-safe)
POST	/v1/sessions/erase-subject	GDPR Art-17 SUBJECT-scoped erasure — forget every session belonging to one data subject
POST	/v1/sessions/{session_id}/turns	Append ordered transcript turns (server-assigned monotonic sequence)
GET	/v1/sessions/{session_id}/transcript	Transcript export — the ordered turns of the session
POST	/v1/sessions/{session_id}/recording	Attach a recording REF (pointer into media-transcode/cdn — never the bytes)
GET	/v1/privacy/policy	THIS tenant's EFFECTIVE privacy policy and the features it voids. READ-ONLY by design — config-flags owns the WRITE (PUT /v1/settings/privacy/policy) and re-exposing a write here would create a second authority for one fact. This answers what the store will ACTUALLY do with the policy.
GET	/health	liveness (db)
GET	/metrics	Prometheus exposition

Schemas

EraseSubjectResult

matched (sessions belonging to the subject) is reported separately from the deleted counts so a zero-match is visible to the compliance fan-out rather than reading as a successful erasure.

Field	Type	Description
success	boolean
capability	string
organization_id	string
disposition	string
selector	string
matched	integer	sessions belonging to the subject
sessions_deleted	integer
turns_deleted	integer	transcript rows removed with those sessions
recordings_deleted	integer	recording REFERENCES; blobs are purged by media-transcode/cdn
dry_run	boolean
would_delete	object	dry-run preview only

Error

Field	Type	Description
error	string	stable machine code (slug), e.g. validation_error, not_found, unauthorized, internal
reason	string	human-readable one-line explanation (no secrets/PII)
detail	object
request_id	string

CreateSessionRequest

Field	Type	Description
organization_id	string	product-tier tenant (I6); resolved anti-spoof when identity is wired
modality	string	voice
external_ref	string	product's own id (call_id / thread_id)
metadata	object

Session

Field	Type	Description
id	string
organization_id	string
modality	string
external_ref	string
status	string	open
turn_count	integer
metadata	object
created_at	string
updated_at	string

Turn

Field	Type	Description
role	string	speaker — user/assistant/system/caller/agent/…
content	string
ts	string	caller event-time (ISO-8601); not the sort key
audio_ref	string	pointer to a media-transcode/cdn segment
seq	integer	server-assigned monotonic per-session order (response only)
metadata	object
created_at	string

AppendTurnsRequest

Field	Type	Description
organization_id	string
turns	array

AppendTurnsResponse

Field	Type	Description
session_id	string
appended	integer
turns	array

Recording

Field	Type	Description
id	string
recording_ref	string	ref/URI into media-transcode/cdn (NOT the bytes)
media_type	string
duration_ms	integer
provider_ref	string	provider-side id (e.g. Twilio Recording SID)
metadata	object
created_at	string

---

Generated by scripts/gen-capability-docs.py from contracts/session-store/v1/openapi.yaml — the contract IS the source of truth; edit the contract, not this page.