Skip to content

workspace API

Workspace Checkin/Checkout

Workspace checkin/checkout provides a transactional editing model for file data: - Checkout: Clears PG tables (face_detections, speaker_detections, pre_chunks) and Qdrant vectors, creating an isolated workspace SQLite for editing. - Checkin: Restores data from the workspace SQLite back to PG and Qdrant, marking the file as Indexed.

This allows safe concurrent editing — while a file is checked out, its main database records are cleared, preventing conflicts.

POST /api/v1/file/:file_uuid/checkout

Auth: Required Scope: file-level

Checkout a file workspace. Clears face detections, speaker detections, pre_chunks from PostgreSQL, deletes Qdrant vectors, and creates a workspace SQLite database for isolated editing.

Example

curl -s -X POST "$API/api/v1/file/$FILE_UUID/checkout" \
  -H "X-API-Key: $KEY"

Response (200)

{
  "file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
  "rows_deleted": 1523,
  "status": "checked_out"
}
Field Type Description
file_uuid string 32-char hex UUID
rows_deleted integer Total rows cleared from PG tables
status string "checked_out"

Error Responses

HTTP When
500 Checkout failed (DB error, workspace creation error)

POST /api/v1/file/:file_uuid/checkin

Auth: Required Scope: file-level

Checkin a file workspace. Restores face detections, speaker detections, pre_chunks from workspace SQLite back to PostgreSQL, re-indexes vectors to Qdrant, and sets video status to Indexed.

Example

curl -s -X POST "$API/api/v1/file/$FILE_UUID/checkin" \
  -H "X-API-Key: $KEY"

Response (200)

{
  "file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
  "pre_chunks_moved": 45,
  "face_detections_moved": 1200,
  "speaker_detections_moved": 320,
  "vectors_moved": 45,
  "status": "indexed"
}
Field Type Description
file_uuid string 32-char hex UUID
pre_chunks_moved integer Pre-chunks restored from workspace
face_detections_moved integer Face detections restored from workspace
speaker_detections_moved integer Speaker detections restored from workspace
vectors_moved integer Vectors re-indexed to Qdrant
status string "indexed"

Error Responses

HTTP When
500 Checkin failed (DB error, workspace not found, vector index error)

GET /api/v1/file/:file_uuid/workspace

Auth: Required Scope: file-level

Check if a workspace SQLite database exists for a file.

Example

curl -s "$API/api/v1/file/$FILE_UUID/workspace" \
  -H "X-API-Key: $KEY"

Response (200)

{
  "file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
  "exists": true
}
Field Type Description
file_uuid string 32-char hex UUID
exists boolean True if workspace SQLite exists

Workflow

  REGISTERED ──→ CHECKED_OUT ──→ INDEXED
     │              │              │
     │          checkout        checkin
     │              │              │
     │     clear PG + Qdrant   restore from SQLite
     │     create workspace    re-index vectors
     │     set status          set status
  1. Register file → status: REGISTERED
  2. Process file → processors run, data stored in PG + Qdrant
  3. Checkout file → clear editable data, create workspace SQLite → status: CHECKED_OUT
  4. Edit workspace via Agent Search / identity binding
  5. Checkin file → restore from workspace SQLite → status: INDEXED
  6. Rebuild TKG if needed after checkin

Updated: 2026-06-20 12:00:00

Version History

Version Date Changes
1.0 2026-10-24 Initial documentation