{"openapi":"3.1.0","info":{"title":"Vitu Flow API","description":"\n## Vitu Flow REST API\n\nWorkflow engine for **cases** (FSM instances). Business fields live in per-case **`metadata` JSON**.\n\n### For API integrators (no UI login)\n\n| Resource | URL |\n|----------|-----|\n| **Developer guides** | [/developer-docs/](/developer-docs/) |\n| **Swagger UI** | [/docs](/docs) |\n| **ReDoc** | [/redoc](/redoc) |\n| **OpenAPI JSON** | [/openapi.json](/openapi.json) |\n\n**Base URL:** the host you opened this page on (Swagger **Servers** dropdown). Examples: `http://127.0.0.1:8000` (local), `https://flow-api.vitu.cloud` (production).\n\n**Auth:** `X-API-Key: vk_...` on routes tagged **integrations** and **embed**.\n\n**Typical flow:** `POST /api/integrations/cases` (optional, `case_create`) → `case_id` → read/post events → `POST /api/embed/tokens` for iframe.\n\nGuides include **curl** and **Python** examples under `/developer-docs/examples/`.\n\n### For internal operators\n\nUse the web app (e.g. `https://flow.vitu.cloud`) with session cookie auth on `/api/auth/*` and `/api/cases/*`.\n","version":"0.1.0"},"paths":{"/api/auth/login":{"post":{"tags":["auth"],"summary":"Login","operationId":"login_api_auth_login_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserRead"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/auth/logout":{"post":{"tags":["auth"],"summary":"Logout","operationId":"logout_api_auth_logout_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response Logout Api Auth Logout Post"}}}}}}},"/api/auth/me":{"get":{"tags":["auth"],"summary":"Me","operationId":"me_api_auth_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserRead"}}}}}}},"/api/auth/sso-status":{"get":{"tags":["auth"],"summary":"Auth Sso Status","description":"Public: whether Google OAuth is configured; exact redirect_uri for Google Cloud Console.","operationId":"auth_sso_status_api_auth_sso_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"anyOf":[{"type":"boolean"},{"type":"string"},{"type":"null"}]},"type":"object","title":"Response Auth Sso Status Api Auth Sso Status Get"}}}}}}},"/api/auth/users":{"get":{"tags":["auth"],"summary":"List Users Admin","operationId":"list_users_admin_api_auth_users_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":200,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/UserAdminRead"},"title":"Response List Users Admin Api Auth Users Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/auth/users/{user_id}":{"delete":{"tags":["auth"],"summary":"Deactivate User Admin","operationId":"deactivate_user_admin_api_auth_users__user_id__delete","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/auth/invites/{invite_id}":{"delete":{"tags":["auth"],"summary":"Revoke Invite Admin","operationId":"revoke_invite_admin_api_auth_invites__invite_id__delete","parameters":[{"name":"invite_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Invite Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/auth/google/start":{"get":{"tags":["auth"],"summary":"Google Oauth Start","operationId":"google_oauth_start_api_auth_google_start_get","parameters":[{"name":"invite","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invite"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/auth/google/callback":{"get":{"tags":["auth"],"summary":"Google Oauth Callback","operationId":"google_oauth_callback_api_auth_google_callback_get","parameters":[{"name":"code","in":"query","required":true,"schema":{"type":"string","title":"Code"}},{"name":"state","in":"query","required":true,"schema":{"type":"string","title":"State"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/auth/invites":{"post":{"tags":["auth"],"summary":"Create Invite","operationId":"create_invite_api_auth_invites_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteCreated"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["auth"],"summary":"List Invites","operationId":"list_invites_api_auth_invites_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":200,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InviteRead"},"title":"Response List Invites Api Auth Invites Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/auth/audit-events":{"get":{"tags":["auth"],"summary":"List Audit Events","operationId":"list_audit_events_api_auth_audit_events_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AuditEventRead"},"title":"Response List Audit Events Api Auth Audit Events Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/auth/api-keys":{"get":{"tags":["api-keys"],"summary":"List Api Keys","operationId":"list_api_keys_api_auth_api_keys_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ApiKeyRead"},"type":"array","title":"Response List Api Keys Api Auth Api Keys Get"}}}}}},"post":{"tags":["api-keys"],"summary":"Create Key","operationId":"create_key_api_auth_api_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreated"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/auth/api-keys/allowed-scopes":{"get":{"tags":["api-keys"],"summary":"Allowed Scopes","operationId":"allowed_scopes_api_auth_api_keys_allowed_scopes_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ApiKeyScope"},"type":"array","title":"Response Allowed Scopes Api Auth Api Keys Allowed Scopes Get"}}}}}}},"/api/auth/api-keys/{key_id}":{"delete":{"tags":["api-keys"],"summary":"Revoke Key","operationId":"revoke_key_api_auth_api_keys__key_id__delete","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Key Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/embed/tokens":{"post":{"tags":["embed"],"summary":"Create Embed Token","description":"Mint a short-lived token for the iframe tracker.\n\nPreferred body: ``{\"case_id\": \"<uuid>\"}`` after resolving the case server-side\n(e.g. ``GET /api/integrations/cases/search?q=...``). The JWT encodes ``case_id``;\nthe iframe never performs metadata search — only the encoded case id.\n\nOptional shortcut: ``metadata_key`` + ``metadata_value`` resolves to the latest case\nbefore minting (same JWT). The browser never sees the API key.","operationId":"create_embed_token_api_embed_tokens_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbedTokenCreate"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbedTokenResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyHeader":[]}]}},"/api/embed/data":{"get":{"tags":["embed"],"summary":"Embed Tracker Data","description":"JSON bundle for the embed page (called by the iframe, token auth only).","operationId":"embed_tracker_data_api_embed_data_get","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string","minLength":10,"title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/embed/tracker":{"get":{"tags":["embed"],"summary":"Embed Tracker Page Api","description":"Alias for ``GET /embed/tracker`` (some integrators expect a path under ``/api/embed``).","operationId":"embed_tracker_page_api_api_embed_tracker_get","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string","minLength":10,"title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/integrations/cases":{"post":{"tags":["integrations"],"summary":"Create Case Integration","description":"Create a workflow case (machine-to-machine).\n\nRequires ``case_create`` scope. Body matches operator ``POST /api/cases``:\n``metadata`` plus ``workflow_id`` or ``workflow_name``.","operationId":"create_case_integration_api_integrations_cases_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseRead"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyHeader":[]}]}},"/api/integrations/cases/by-metadata":{"get":{"tags":["integrations"],"summary":"Resolve Case By Metadata","description":"Resolve the latest case UUID for metadata[key]==value (read-only).\n\nUse the returned ``id`` with ``POST /api/integrations/cases/{case_id}/events``.\nEvent writes are not accepted via metadata shortcuts (avoids ambiguous matches).","operationId":"resolve_case_by_metadata_api_integrations_cases_by_metadata_get","parameters":[{"name":"metadata_key","in":"query","required":true,"schema":{"type":"string","minLength":1,"title":"Metadata Key"}},{"name":"metadata_value","in":"query","required":true,"schema":{"type":"string","minLength":1,"title":"Metadata Value"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseRead"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyHeader":[]}]}},"/api/integrations/cases/search":{"get":{"tags":["integrations"],"summary":"Search Cases Integration","description":"Search cases by metadata JSON and workflow fields (API key).","operationId":"search_cases_integration_api_integrations_cases_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"title":"Q"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CaseListRead"},"title":"Response Search Cases Integration Api Integrations Cases Search Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyHeader":[]}]}},"/api/integrations/cases/{case_id}":{"get":{"tags":["integrations"],"summary":"Get Case By Id","operationId":"get_case_by_id_api_integrations_cases__case_id__get","parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Case Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseRead"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyHeader":[]}]}},"/api/integrations/cases/{case_id}/events/{event_id}":{"get":{"tags":["integrations"],"summary":"Get Event By Case Id","operationId":"get_event_by_case_id_api_integrations_cases__case_id__events__event_id__get","parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Case Id"}},{"name":"event_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Event Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseEventRead"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyHeader":[]}]}},"/api/integrations/cases/{case_id}/events":{"get":{"tags":["integrations"],"summary":"Get Events By Case Id","operationId":"get_events_by_case_id_api_integrations_cases__case_id__events_get","parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Case Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseEventsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyHeader":[]}]},"post":{"tags":["integrations"],"summary":"Post Event By Case Id","operationId":"post_event_by_case_id_api_integrations_cases__case_id__events_post","parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Case Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalEventCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalEventCreated"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyHeader":[]}]}},"/api/integrations/cases/by-metadata/events":{"get":{"tags":["integrations"],"summary":"Get Events By Metadata","description":"Resolve the latest case where ``metadata[metadata_key] == metadata_value``.","operationId":"get_events_by_metadata_api_integrations_cases_by_metadata_events_get","parameters":[{"name":"metadata_key","in":"query","required":true,"schema":{"type":"string","minLength":1,"title":"Metadata Key"}},{"name":"metadata_value","in":"query","required":true,"schema":{"type":"string","minLength":1,"title":"Metadata Value"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseEventsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyHeader":[]}]}},"/api/cases":{"get":{"tags":["cases"],"summary":"List Cases","operationId":"list_cases_api_cases_get","parameters":[{"name":"stage","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stage"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"assignment_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assignment Type"}},{"name":"assignment_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assignment Id"}},{"name":"metadata_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metadata Key"}},{"name":"metadata_value","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metadata Value"}},{"name":"workflow_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workflow Name"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search metadata JSON and indexed fields","title":"Q"},"description":"Search metadata JSON and indexed fields"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CaseListRead"},"title":"Response List Cases Api Cases Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["cases"],"summary":"Create Case","operationId":"create_case_api_cases_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseRead"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/cases/search":{"get":{"tags":["cases"],"summary":"Search Cases","operationId":"search_cases_api_cases_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Search metadata JSON and workflow fields","title":"Q"},"description":"Search metadata JSON and workflow fields"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CaseListRead"},"title":"Response Search Cases Api Cases Search Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/cases/import":{"post":{"tags":["cases"],"summary":"Import Case Metadata File","operationId":"import_case_metadata_file_api_cases_import_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_import_case_metadata_file_api_cases_import_post"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseRead"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/cases/{case_id}":{"get":{"tags":["cases"],"summary":"Get Case","operationId":"get_case_api_cases__case_id__get","parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Case Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseRead"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/cases/{case_id}/metadata":{"patch":{"tags":["cases"],"summary":"Update Case Metadata","operationId":"update_case_metadata_api_cases__case_id__metadata_patch","parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Case Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseMetadataUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseRead"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/cases/{case_id}/stages":{"get":{"tags":["cases"],"summary":"List Case Stages","operationId":"list_case_stages_api_cases__case_id__stages_get","parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Case Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseStagesRead"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/cases/{case_id}/stages/{stage_id}":{"get":{"tags":["cases"],"summary":"Get Case Stage","operationId":"get_case_stage_api_cases__case_id__stages__stage_id__get","parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Case Id"}},{"name":"stage_id","in":"path","required":true,"schema":{"type":"string","title":"Stage Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StageDetailRead"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/cases/{case_id}/events/{event_id}":{"get":{"tags":["cases"],"summary":"Get Case Event Detail","operationId":"get_case_event_detail_api_cases__case_id__events__event_id__get","parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Case Id"}},{"name":"event_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Event Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseEventRead"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/cases/{case_id}/events":{"get":{"tags":["cases"],"summary":"List Case Events","operationId":"list_case_events_api_cases__case_id__events_get","parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Case Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CaseEventRead"},"title":"Response List Case Events Api Cases  Case Id  Events Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["cases"],"summary":"Post Case Event","operationId":"post_case_event_api_cases__case_id__events_post","parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Case Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseEventCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseEventRead"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/workflows":{"get":{"tags":["workflows"],"summary":"List Workflows","description":"Directory of workflow families (each has its own version history and JSON definition).","operationId":"list_workflows_api_workflows_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/WorkflowFamilySummary"},"type":"array","title":"Response List Workflows Api Workflows Get"}}}}}},"post":{"tags":["workflows"],"summary":"Create Workflow Version","description":"Save canvas edits as a new version (optional publish to make it active).","operationId":"create_workflow_version_api_workflows_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowSaveBody"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowSaveResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/workflows/changelog":{"get":{"tags":["workflows"],"summary":"Download Workflow Changelog","description":"Download full changelog for a workflow family (comments + structural diffs).","operationId":"download_workflow_changelog_api_workflows_changelog_get","parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","minLength":1,"title":"Name"}},{"name":"format","in":"query","required":false,"schema":{"enum":["json","csv"],"type":"string","description":"Download format","default":"json","title":"Format"},"description":"Download format"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/workflows/changelog/entries":{"get":{"tags":["workflows"],"summary":"List Workflow Changelog Entries","description":"JSON list of changelog rows (same data as download, for in-app display).","operationId":"list_workflow_changelog_entries_api_workflows_changelog_entries_get","parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","minLength":1,"title":"Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowChangelogEntryRead"},"title":"Response List Workflow Changelog Entries Api Workflows Changelog Entries Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/workflows/families":{"post":{"tags":["workflows"],"summary":"Create Workflow Family Route","operationId":"create_workflow_family_route_api_workflows_families_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowCreateFamilyBody"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowSaveResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["workflows"],"summary":"Delete Workflow Family Route","description":"Permanently delete all versions of a workflow family (cannot undo).","operationId":"delete_workflow_family_route_api_workflows_families_delete","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowDeleteFamilyBody"}}},"required":true},"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/workflows/families/rename":{"patch":{"tags":["workflows"],"summary":"Rename Workflow Family Route","description":"Rename a workflow family (all versions and changelog history use the new name).","operationId":"rename_workflow_family_route_api_workflows_families_rename_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRenameFamilyBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRenameFamilyResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/workflows/active":{"get":{"tags":["workflows"],"summary":"Get Active Workflow","operationId":"get_active_workflow_api_workflows_active_get","parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Workflow family name","title":"Name"},"description":"Workflow family name"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRead"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/workflows/versions":{"get":{"tags":["workflows"],"summary":"List Workflow Versions","operationId":"list_workflow_versions_api_workflows_versions_get","parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","minLength":1,"title":"Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowVersionSummary"},"title":"Response List Workflow Versions Api Workflows Versions Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/workflows/{workflow_id}/changelog":{"get":{"tags":["workflows"],"summary":"Download Version Changelog","description":"Download changelog for a single workflow version (comment + structural diff).","operationId":"download_version_changelog_api_workflows__workflow_id__changelog_get","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workflow Id"}},{"name":"format","in":"query","required":false,"schema":{"enum":["json","csv"],"type":"string","description":"Download format","default":"json","title":"Format"},"description":"Download format"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/workflows/{workflow_id}/rollback":{"post":{"tags":["workflows"],"summary":"Rollback Workflow","description":"Copy an older version's definition into a new version and publish it (audit-friendly rollback).","operationId":"rollback_workflow_api_workflows__workflow_id__rollback_post","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workflow Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowActionComment"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowSaveResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/workflows/{workflow_id}/publish":{"post":{"tags":["workflows"],"summary":"Publish Workflow Version","operationId":"publish_workflow_version_api_workflows__workflow_id__publish_post","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workflow Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowActionComment"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRead"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/workflows/{workflow_id}":{"get":{"tags":["workflows"],"summary":"Get Workflow","operationId":"get_workflow_api_workflows__workflow_id__get","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workflow Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRead"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/embed/tracker.reference.css":{"get":{"tags":["embed"],"summary":"Embed Tracker Reference Css","description":"Reference skin for the embed tracker (partners may copy or replace).\n\nStable markup contract: ``app/embed/tracker.html``.","operationId":"embed_tracker_reference_css_embed_tracker_reference_css_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/embed/tracker":{"get":{"tags":["embed"],"summary":"Embed Tracker Page","description":"Standalone workflow history page for iframe embedding.\n\nOpen the URL returned by ``POST /api/embed/tokens`` (includes ``token`` query param).\nStyling is loaded from ``tracker.reference.css`` unless overridden.","operationId":"embed_tracker_page_embed_tracker_get","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string","minLength":10,"title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health":{"get":{"tags":["health"],"summary":"Health","description":"Liveness check for load balancers and monitoring.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response Health Health Get"}}}}}}}},"components":{"schemas":{"ActorRef":{"properties":{"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Id"},"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"}},"type":"object","title":"ActorRef"},"ApiKeyCreate":{"properties":{"name":{"type":"string","maxLength":128,"minLength":1,"title":"Name"},"scopes":{"items":{"$ref":"#/components/schemas/ApiKeyScope"},"type":"array","minItems":1,"title":"Scopes"}},"type":"object","required":["name","scopes"],"title":"ApiKeyCreate"},"ApiKeyCreated":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"key_prefix":{"type":"string","title":"Key Prefix"},"scopes":{"items":{"$ref":"#/components/schemas/ApiKeyScope"},"type":"array","title":"Scopes"},"is_active":{"type":"boolean","title":"Is Active"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used At"},"api_key":{"type":"string","title":"Api Key"}},"type":"object","required":["id","name","key_prefix","scopes","is_active","created_at","last_used_at","api_key"],"title":"ApiKeyCreated","description":"Returned once when the key is created; includes the secret."},"ApiKeyRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"key_prefix":{"type":"string","title":"Key Prefix"},"scopes":{"items":{"$ref":"#/components/schemas/ApiKeyScope"},"type":"array","title":"Scopes"},"is_active":{"type":"boolean","title":"Is Active"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used At"}},"type":"object","required":["id","name","key_prefix","scopes","is_active","created_at","last_used_at"],"title":"ApiKeyRead"},"ApiKeyScope":{"type":"string","enum":["case_read","case_create","event_write"],"title":"ApiKeyScope"},"AssignmentType":{"type":"string","enum":["unassigned","system","employee","queue"],"title":"AssignmentType"},"AuditEventRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"occurred_at":{"type":"string","format":"date-time","title":"Occurred At"},"actor_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor User Id"},"action":{"type":"string","title":"Action"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id"},"details":{"additionalProperties":true,"type":"object","title":"Details"},"ip_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ip Address"},"user_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Agent"}},"type":"object","required":["id","occurred_at","actor_user_id","action","entity_type","entity_id","details","ip_address","user_agent"],"title":"AuditEventRead"},"Body_import_case_metadata_file_api_cases_import_post":{"properties":{"metadata_file":{"type":"string","contentMediaType":"application/octet-stream","title":"Metadata File","description":"UTF-8 JSON object (integrator-defined fields)"},"workflow_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Workflow Id"},"workflow_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workflow Name"}},"type":"object","required":["metadata_file"],"title":"Body_import_case_metadata_file_api_cases_import_post"},"CaseCreate":{"properties":{"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Integrator JSON object (arbitrary keys; engine does not validate domain fields)"},"workflow_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Workflow Id","description":"Bind to a specific workflow version."},"workflow_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workflow Name","description":"Use the active version of this workflow family (if workflow_id is omitted)."}},"type":"object","title":"CaseCreate","description":"Create a workflow instance. All domain fields live in ``metadata``."},"CaseEventCreate":{"properties":{"event_type":{"type":"string","maxLength":256,"minLength":1,"title":"Event Type"},"payload":{"additionalProperties":true,"type":"object","title":"Payload"},"source_system":{"type":"string","maxLength":128,"minLength":1,"title":"Source System"}},"type":"object","required":["event_type","source_system"],"title":"CaseEventCreate"},"CaseEventRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"case_id":{"type":"string","format":"uuid","title":"Case Id"},"event_type":{"type":"string","title":"Event Type"},"payload":{"additionalProperties":true,"type":"object","title":"Payload"},"source_system":{"type":"string","title":"Source System"},"actor_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor Id"},"occurred_at":{"type":"string","format":"date-time","title":"Occurred At"}},"type":"object","required":["id","case_id","event_type","payload","source_system","actor_id","occurred_at"],"title":"CaseEventRead"},"CaseEventsResponse":{"properties":{"case_id":{"type":"string","format":"uuid","title":"Case Id"},"metadata_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metadata Key"},"metadata_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metadata Value"},"events":{"items":{"$ref":"#/components/schemas/CaseEventRead"},"type":"array","title":"Events"}},"type":"object","required":["case_id","events"],"title":"CaseEventsResponse"},"CaseListRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Integrator-defined case JSON"},"workflow_id":{"type":"string","format":"uuid","title":"Workflow Id"},"stage":{"type":"string","title":"Stage"},"assignment_type":{"$ref":"#/components/schemas/AssignmentType"},"assignment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assignment Id"},"assignment_since":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Assignment Since"},"status":{"$ref":"#/components/schemas/CaseStatus"},"exception_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Exception Reason"},"sla_due_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Sla Due At"},"last_event_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Event At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"workflow_name":{"type":"string","title":"Workflow Name"},"workflow_version":{"type":"integer","title":"Workflow Version"}},"type":"object","required":["id","workflow_id","stage","assignment_type","assignment_id","assignment_since","status","exception_reason","sla_due_at","last_event_at","created_at","updated_at","workflow_name","workflow_version"],"title":"CaseListRead","description":"Case row for list views (includes bound workflow family + version)."},"CaseMetadataUpdate":{"properties":{"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"merge":{"type":"boolean","title":"Merge","description":"If true, shallow-merge into existing metadata instead of replacing.","default":false}},"type":"object","required":["metadata"],"title":"CaseMetadataUpdate","description":"Replace or merge case metadata (must remain a JSON object)."},"CaseRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Integrator-defined case JSON"},"workflow_id":{"type":"string","format":"uuid","title":"Workflow Id"},"stage":{"type":"string","title":"Stage"},"assignment_type":{"$ref":"#/components/schemas/AssignmentType"},"assignment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assignment Id"},"assignment_since":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Assignment Since"},"status":{"$ref":"#/components/schemas/CaseStatus"},"exception_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Exception Reason"},"sla_due_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Sla Due At"},"last_event_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Event At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","workflow_id","stage","assignment_type","assignment_id","assignment_since","status","exception_reason","sla_due_at","last_event_at","created_at","updated_at"],"title":"CaseRead"},"CaseStagesRead":{"properties":{"case_id":{"type":"string","format":"uuid","title":"Case Id"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Case integrator JSON snapshot"},"current_stage":{"type":"string","title":"Current Stage"},"stage_fields":{"items":{"$ref":"#/components/schemas/StageFieldDef"},"type":"array","title":"Stage Fields","description":"Parameter schema from workflow definition (stage_fields)"},"stages":{"items":{"$ref":"#/components/schemas/StageDetailRead"},"type":"array","title":"Stages"}},"type":"object","required":["case_id","current_stage","stages"],"title":"CaseStagesRead"},"CaseStatus":{"type":"string","enum":["in_progress","waiting_external","awaiting_human_action","blocked_exception","done"],"title":"CaseStatus","description":"Runtime status for a workflow instance (orthogonal to workflow state id)."},"EmbedTokenCreate":{"properties":{"case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Case Id","description":"Vitu case UUID (preferred). Resolve via GET /api/integrations/cases/search first."},"metadata_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metadata Key","description":"Optional shortcut: metadata field name (integrator-defined)."},"metadata_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metadata Value","description":"Optional shortcut: exact metadata value for metadata_key."},"ttl_minutes":{"anyOf":[{"type":"integer","maximum":1440.0,"minimum":1.0},{"type":"null"}],"title":"Ttl Minutes"}},"type":"object","title":"EmbedTokenCreate","description":"Mint a short-lived iframe token (API key, server-side only).\n\nPreferred: ``case_id`` after resolving the case via search or your own store.\nOptional shortcut: ``metadata_key`` + ``metadata_value`` (server resolves to latest case).\nThe iframe always loads by case UUID; business keys live in metadata only."},"EmbedTokenResponse":{"properties":{"token":{"type":"string","title":"Token"},"case_id":{"type":"string","format":"uuid","title":"Case Id"},"embed_url":{"type":"string","title":"Embed Url"},"data_url":{"type":"string","title":"Data Url"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"}},"type":"object","required":["token","case_id","embed_url","data_url","expires_at"],"title":"EmbedTokenResponse"},"EventAtStageRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"event_type":{"type":"string","title":"Event Type"},"occurred_at":{"type":"string","format":"date-time","title":"Occurred At"},"source_system":{"type":"string","title":"Source System"},"actor":{"anyOf":[{"$ref":"#/components/schemas/ActorRef"},{"type":"null"}]},"payload":{"additionalProperties":true,"type":"object","title":"Payload"},"caused_transition":{"type":"boolean","title":"Caused Transition","default":false},"transition_to":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Transition To"}},"type":"object","required":["id","event_type","occurred_at","source_system"],"title":"EventAtStageRead"},"ExternalEventCreate":{"properties":{"event_type":{"type":"string","maxLength":256,"minLength":1,"title":"Event Type"},"payload":{"additionalProperties":true,"type":"object","title":"Payload"},"source_system":{"type":"string","maxLength":128,"minLength":1,"title":"Source System"}},"type":"object","required":["event_type","source_system"],"title":"ExternalEventCreate","description":"Inbound event from an external system (API key auth)."},"ExternalEventCreated":{"properties":{"case_id":{"type":"string","format":"uuid","title":"Case Id"},"event":{"$ref":"#/components/schemas/CaseEventRead"},"metadata_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metadata Key","description":"Present when the case was resolved via metadata lookup"},"metadata_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metadata Value"}},"type":"object","required":["case_id","event"],"title":"ExternalEventCreated"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"InviteCreate":{"properties":{"email":{"type":"string","format":"email","title":"Email"},"role":{"$ref":"#/components/schemas/UserRole"},"user_kind":{"$ref":"#/components/schemas/UserKind","default":"internal"}},"type":"object","required":["email","role"],"title":"InviteCreate"},"InviteCreated":{"properties":{"email":{"type":"string","title":"Email"},"invite_url":{"type":"string","title":"Invite Url"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"}},"type":"object","required":["email","invite_url","expires_at"],"title":"InviteCreated","description":"Returned once when an invite is created; includes the secret link."},"InviteRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"email":{"type":"string","title":"Email"},"role":{"$ref":"#/components/schemas/UserRole"},"user_kind":{"$ref":"#/components/schemas/UserKind"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"},"accepted_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Accepted At"}},"type":"object","required":["id","email","role","user_kind","created_at","expires_at","accepted_at"],"title":"InviteRead"},"LoginRequest":{"properties":{"username":{"type":"string","minLength":1,"title":"Username"},"password":{"type":"string","minLength":1,"title":"Password"}},"type":"object","required":["username","password"],"title":"LoginRequest"},"StageDetailRead":{"properties":{"stage_id":{"type":"string","title":"Stage Id"},"label":{"type":"string","title":"Label"},"description":{"type":"string","title":"Description"},"type":{"type":"string","title":"Type"},"is_current":{"type":"boolean","title":"Is Current"},"parameters":{"additionalProperties":true,"type":"object","title":"Parameters","description":"Values for keys declared in the workflow stage_fields schema"},"visits":{"items":{"$ref":"#/components/schemas/StageVisitRead"},"type":"array","title":"Visits"},"events_here":{"items":{"$ref":"#/components/schemas/EventAtStageRead"},"type":"array","title":"Events Here","description":"Domain events recorded while the case was in this stage"}},"type":"object","required":["stage_id","label","description","type","is_current"],"title":"StageDetailRead"},"StageFieldDef":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"},"type":{"type":"string","title":"Type","default":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"type":"object","required":["key","label"],"title":"StageFieldDef","description":"Declared in workflow JSON ``stage_fields`` — drives API/UI parameter display."},"StageVisitRead":{"properties":{"entered_at":{"type":"string","format":"date-time","title":"Entered At"},"exited_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Exited At"},"trigger_event":{"type":"string","title":"Trigger Event"},"source_system":{"type":"string","title":"Source System"},"actor":{"anyOf":[{"$ref":"#/components/schemas/ActorRef"},{"type":"null"}]}},"type":"object","required":["entered_at","trigger_event","source_system"],"title":"StageVisitRead"},"UserAdminRead":{"properties":{"username":{"type":"string","title":"Username"},"email":{"type":"string","format":"email","title":"Email"},"user_kind":{"$ref":"#/components/schemas/UserKind"},"role":{"$ref":"#/components/schemas/UserRole"},"id":{"type":"string","format":"uuid","title":"Id"},"is_active":{"type":"boolean","title":"Is Active"},"case_label":{"type":"string","title":"Case Label","default":"Case"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"has_password":{"type":"boolean","title":"Has Password"},"sso_google":{"type":"boolean","title":"Sso Google"}},"type":"object","required":["username","email","user_kind","role","id","is_active","created_at","has_password","sso_google"],"title":"UserAdminRead","description":"Admin directory: sign-in modalities (no secrets)."},"UserKind":{"type":"string","enum":["internal","external"],"title":"UserKind","description":"Who the account is for: Vitu staff UI vs external integrators."},"UserRead":{"properties":{"username":{"type":"string","title":"Username"},"email":{"type":"string","format":"email","title":"Email"},"user_kind":{"$ref":"#/components/schemas/UserKind"},"role":{"$ref":"#/components/schemas/UserRole"},"id":{"type":"string","format":"uuid","title":"Id"},"is_active":{"type":"boolean","title":"Is Active"},"case_label":{"type":"string","title":"Case Label","default":"Case"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["username","email","user_kind","role","id","is_active","created_at"],"title":"UserRead"},"UserRole":{"type":"string","enum":["admin","workflow_editor","operator","viewer","case_lookup"],"title":"UserRole"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WorkflowActionComment":{"properties":{"comment":{"type":"string","maxLength":4000,"minLength":1,"title":"Comment"}},"type":"object","required":["comment"],"title":"WorkflowActionComment","description":"Required explanation for workflow mutations (saved in changelog)."},"WorkflowChangelogEntryRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"occurred_at":{"type":"string","format":"date-time","title":"Occurred At"},"workflow_name":{"type":"string","title":"Workflow Name"},"action":{"type":"string","title":"Action"},"comment":{"type":"string","title":"Comment"},"actor_username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actor Username"},"workflow_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Workflow Id"},"workflow_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Workflow Version"},"from_workflow_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"From Workflow Id"},"changes_summary":{"type":"string","title":"Changes Summary"},"changes":{"additionalProperties":true,"type":"object","title":"Changes"}},"type":"object","required":["id","occurred_at","workflow_name","action","comment","changes_summary","changes"],"title":"WorkflowChangelogEntryRead"},"WorkflowCreateFamilyBody":{"properties":{"comment":{"type":"string","maxLength":4000,"minLength":1,"title":"Comment"},"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name"},"definition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Definition","description":"Optional initial JSON; defaults to a single start state"},"publish":{"type":"boolean","title":"Publish","description":"Mark version 1 as active for this family","default":true}},"type":"object","required":["comment","name"],"title":"WorkflowCreateFamilyBody","description":"Create a new workflow family (version 1)."},"WorkflowDeleteFamilyBody":{"properties":{"comment":{"type":"string","maxLength":4000,"minLength":1,"title":"Comment"},"confirm_name":{"type":"string","maxLength":255,"minLength":1,"title":"Confirm Name","description":"Type the workflow family name exactly to confirm permanent deletion."}},"type":"object","required":["comment","confirm_name"],"title":"WorkflowDeleteFamilyBody","description":"Delete an entire workflow family (all versions). Name must match exactly when stripped."},"WorkflowFamilySummary":{"properties":{"name":{"type":"string","title":"Name"},"version_count":{"type":"integer","title":"Version Count"},"active_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Active Version"},"active_workflow_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Active Workflow Id"},"latest_version":{"type":"integer","title":"Latest Version"},"latest_workflow_id":{"type":"string","format":"uuid","title":"Latest Workflow Id"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"state_count":{"type":"integer","title":"State Count","default":0},"transition_count":{"type":"integer","title":"Transition Count","default":0}},"type":"object","required":["name","version_count","latest_version","latest_workflow_id","updated_at"],"title":"WorkflowFamilySummary","description":"One row per workflow family (all versions share the same name)."},"WorkflowRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"version":{"type":"integer","title":"Version"},"is_active":{"type":"boolean","title":"Is Active"},"definition":{"additionalProperties":true,"type":"object","title":"Definition"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","name","version","is_active","definition","created_at","updated_at"],"title":"WorkflowRead"},"WorkflowRenameFamilyBody":{"properties":{"comment":{"type":"string","maxLength":4000,"minLength":1,"title":"Comment"},"from_name":{"type":"string","maxLength":255,"minLength":1,"title":"From Name","description":"Current workflow family name"},"new_name":{"type":"string","maxLength":255,"minLength":1,"title":"New Name","description":"New workflow family name"}},"type":"object","required":["comment","from_name","new_name"],"title":"WorkflowRenameFamilyBody","description":"Rename a workflow family (all versions share the new name)."},"WorkflowRenameFamilyResult":{"properties":{"name":{"type":"string","title":"Name"},"version_count":{"type":"integer","title":"Version Count"}},"type":"object","required":["name","version_count"],"title":"WorkflowRenameFamilyResult"},"WorkflowSaveBody":{"properties":{"comment":{"type":"string","maxLength":4000,"minLength":1,"title":"Comment"},"definition":{"additionalProperties":true,"type":"object","title":"Definition"},"source_workflow_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Workflow Id","description":"Workflow row this edit is based on; used for name + version lineage"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Override workflow family name"},"publish":{"type":"boolean","title":"Publish","description":"If true, deactivate other versions with the same name and activate this one","default":false}},"type":"object","required":["comment","definition"],"title":"WorkflowSaveBody","description":"Create a new workflow version from an edited definition."},"WorkflowSaveResult":{"properties":{"workflow":{"$ref":"#/components/schemas/WorkflowRead"},"validation_warnings":{"items":{"type":"string"},"type":"array","title":"Validation Warnings"}},"type":"object","required":["workflow"],"title":"WorkflowSaveResult"},"WorkflowVersionSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"version":{"type":"integer","title":"Version"},"is_active":{"type":"boolean","title":"Is Active"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"comment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment"},"has_changelog":{"type":"boolean","title":"Has Changelog","default":false}},"type":"object","required":["id","name","version","is_active","created_at","updated_at"],"title":"WorkflowVersionSummary"}},"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Integration API key issued by your Vitu administrator (prefix vk_)."}}},"tags":[{"name":"integrations","description":"**Machine-to-machine APIs** for TMS and partners. Authenticate with `X-API-Key: vk_...` (scopes `case_read` / `case_create` / `event_write`). See `/developer-docs/integration-api.md`."},{"name":"embed","description":"**Iframe embed** — mint short-lived tokens server-side (`POST /api/embed/tokens`), then load `embed_url` in the browser. Never pass API keys to the iframe. See `/developer-docs/embed-tracker.md`."},{"name":"auth","description":"Session login for internal web UI (not used by API-key integrators)."},{"name":"cases","description":"Case CRUD and events (session auth — internal operators)."},{"name":"workflows","description":"Workflow editor APIs (session auth — internal)."},{"name":"api-keys","description":"API key management (session auth — admins)."}],"servers":[{"url":"/","description":"Current host (this deployment)"},{"url":"http://127.0.0.1:8000","description":"Local development"},{"url":"https://flow-api.vitu.cloud","description":"Production"}]}